{
  "openapi": "3.1.0",
  "info": {
    "title": "Mast API",
    "version": "1.0.2",
    "description": "The API a company’s own systems call Mast with: its customers, its products, its suppliers, its invoices, and its books for reading. A key acts in one company, with the rights of the role it was given. Only additions are made to this contract: a field or a value may appear, none goes away."
  },
  "servers": [
    {
      "url": "https://api.mastfinance.io/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Account",
      "description": "The key calling and the company it acts in."
    },
    {
      "name": "Customers",
      "description": "The company’s customers, addressed by the back office’s own reference."
    },
    {
      "name": "Products",
      "description": "What the company sells, addressed by the back office’s own reference."
    },
    {
      "name": "Invoices",
      "description": "Draft, issue, send and read customer invoices."
    },
    {
      "name": "Credit notes",
      "description": "The credit notes issued against invoices, read only."
    },
    {
      "name": "Payments",
      "description": "What customers paid against invoices, read only."
    },
    {
      "name": "Accounting",
      "description": "The chart of accounts, the journal and the trial balance, read only."
    },
    {
      "name": "Banking",
      "description": "Bank accounts and their lines, read only."
    },
    {
      "name": "Purchases",
      "description": "Suppliers, addressed by the back office’s own reference, and their bills, read only."
    }
  ],
  "paths": {
    "/ext/me": {
      "get": {
        "operationId": "account.me",
        "tags": [
          "Account"
        ],
        "summary": "The key calling and its company",
        "description": "The first call to make with a new key. It asks no right, so it tells a key that works from one that does not before any other call is tried.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The key and its company.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyAndCompany"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/me"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/me"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/me"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/me"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/me"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/me"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/me"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/me"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": null,
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_whoami"
      }
    },
    "/ext/company": {
      "get": {
        "operationId": "company.read",
        "tags": [
          "Account"
        ],
        "summary": "The company and its fiscal years",
        "description": "What a reader needs before the books: the base currency, the fiscal years, the VAT registration and today’s accounting day.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The company.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_COMPANY_NOT_FOUND`: The key's company no longer exists.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_COMPANY_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "The key's company no longer exists.",
                      "code": "EXT_COMPANY_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/company"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Company Profile",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_get_company"
      }
    },
    "/ext/customers": {
      "get": {
        "operationId": "customers.list",
        "tags": [
          "Customers"
        ],
        "summary": "The customers changed since a moment",
        "description": "Every customer of the company, yours and the ones people made in Mast (`externalRef` null), oldest change first. A customer deleted in Mast drops out of the list.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most: 50 when left out, never more than 100.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of customers.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Customer"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_customers"
      },
      "post": {
        "operationId": "customers.create",
        "tags": [
          "Customers"
        ],
        "summary": "Make a customer",
        "description": "Makes a customer under your own id. To make it or change it in one call whatever its state, use `PUT /ext/customers/{externalRef}`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalRef": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$",
                    "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "business",
                      "individual"
                    ],
                    "description": "`business` for a company, named by `companyName`; `individual` for a person, named by `firstName` and `lastName`."
                  },
                  "email": {
                    "type": "string",
                    "maxLength": 254,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
                    "description": "The address invoices and reminders are sent to. Every customer of Mast has one."
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200,
                        "description": "Street and number, on one line."
                      },
                      "postalCode": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 20
                      },
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1,
                        "maxLength": 100,
                        "description": "The country's name, as the customer's card in Mast writes it (\"France\", \"Germany\"). Left out, the company's own country."
                      }
                    },
                    "required": [
                      "street",
                      "postalCode",
                      "city"
                    ],
                    "description": "The billing address: what the customer's invoices print."
                  },
                  "companyName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "Required for a business."
                  },
                  "firstName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "Required for an individual."
                  },
                  "lastName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "Required for an individual."
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "Mast keeps it in its international form, without spaces (`+41440000000`), and serves it so. Null or an empty string removes it."
                  },
                  "language": {
                    "description": "The language the customer's invoices and reminders are written in. Left out on a create, the company's own.",
                    "type": "string",
                    "enum": [
                      "de",
                      "fr",
                      "it",
                      "en"
                    ]
                  },
                  "vatNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "The customer's VAT number, in its country's format (`CHE-123.456.789 MWST`, `DE123456789`). Null or an empty string removes it."
                  },
                  "registrationNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100,
                    "description": "Its commercial-register number (a UID, or a foreign registry's id). Null or an empty string removes it."
                  },
                  "defaultDiscountPercent": {
                    "description": "The discount Mast holds for this customer, in percent; 0 for none. An invoice takes it only when it says `applyCustomerDefaultDiscount`.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "paymentTermsDays": {
                    "description": "Its net payment terms in whole days, 0 for due on receipt. An invoice that names no terms takes them. 30 when never set.",
                    "type": "number"
                  }
                },
                "required": [
                  "externalRef",
                  "type",
                  "email",
                  "address"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The customer made.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CUSTOMER_INVALID`: This customer is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This customer is not valid.",
                      "code": "EXT_CUSTOMER_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_CUSTOMER_EXISTS`: A customer with this externalRef already exists in the company: update it with PATCH or PUT.\n\n`EXT_CUSTOMER_ARCHIVED`: The customer with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`CUSTOMER_NAME_EXISTS`: If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_EXISTS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A customer with this externalRef already exists in the company: update it with PATCH or PUT.",
                      "code": "EXT_CUSTOMER_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "EXT_CUSTOMER_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The customer with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_CUSTOMER_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "CUSTOMER_NAME_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A customer named \"Muster Handel AG\" with the same billing address and email address already exists. Change one of the three, or edit the existing entry.",
                      "code": "CUSTOMER_NAME_EXISTS",
                      "details": {
                        "name": "Muster Handel AG"
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: externalRef: Required, type: Required, email: Required, address: Required",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "externalRef",
                            "message": "Required"
                          },
                          {
                            "field": "type",
                            "message": "Required"
                          },
                          {
                            "field": "email",
                            "message": "Required"
                          },
                          {
                            "field": "address",
                            "message": "Required"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer",
          "action": "create"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/customers/{externalRef}": {
      "get": {
        "operationId": "customers.read",
        "tags": [
          "Customers"
        ],
        "summary": "A customer, by your reference",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The customer.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_CUSTOMER_NOT_FOUND`: No customer of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No customer of the company has this reference.",
                      "code": "EXT_CUSTOMER_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_get_customer"
      },
      "put": {
        "operationId": "customers.upsert",
        "tags": [
          "Customers"
        ],
        "summary": "Make or change a customer",
        "description": "The call a sync makes: when the company has no customer under this reference it is made, and the body must then hold what a creation needs (type, name, e-mail, address); else the fields given are changed and the others stay. Safe to repeat.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "description": "`business` for a company, named by `companyName`; `individual` for a person, named by `firstName` and `lastName`.",
                    "type": "string",
                    "enum": [
                      "business",
                      "individual"
                    ]
                  },
                  "email": {
                    "description": "The address invoices and reminders are sent to. Every customer of Mast has one.",
                    "type": "string",
                    "maxLength": 254,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                  },
                  "address": {
                    "description": "The billing address: what the customer's invoices print.",
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200,
                        "description": "Street and number, on one line."
                      },
                      "postalCode": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 20
                      },
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1,
                        "maxLength": 100,
                        "description": "The country's name, as the customer's card in Mast writes it (\"France\", \"Germany\"). Left out, the company's own country."
                      }
                    },
                    "required": [
                      "street",
                      "postalCode",
                      "city"
                    ]
                  },
                  "companyName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "Required for a business."
                  },
                  "firstName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "Required for an individual."
                  },
                  "lastName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "Required for an individual."
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "Mast keeps it in its international form, without spaces (`+41440000000`), and serves it so. Null or an empty string removes it."
                  },
                  "language": {
                    "description": "The language the customer's invoices and reminders are written in. Left out on a create, the company's own.",
                    "type": "string",
                    "enum": [
                      "de",
                      "fr",
                      "it",
                      "en"
                    ]
                  },
                  "vatNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "The customer's VAT number, in its country's format (`CHE-123.456.789 MWST`, `DE123456789`). Null or an empty string removes it."
                  },
                  "registrationNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100,
                    "description": "Its commercial-register number (a UID, or a foreign registry's id). Null or an empty string removes it."
                  },
                  "defaultDiscountPercent": {
                    "description": "The discount Mast holds for this customer, in percent; 0 for none. An invoice takes it only when it says `applyCustomerDefaultDiscount`.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "paymentTermsDays": {
                    "description": "Its net payment terms in whole days, 0 for due on receipt. An invoice that names no terms takes them. 30 when never set.",
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The customer, changed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "201": {
            "description": "The reference was new: the customer was made.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CUSTOMER_INVALID`: This customer is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This customer is not valid.",
                      "code": "EXT_CUSTOMER_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_CUSTOMER_ARCHIVED`: The customer with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`CUSTOMER_NAME_EXISTS`: If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The customer with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_CUSTOMER_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "CUSTOMER_NAME_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A customer named \"Muster Handel AG\" with the same billing address and email address already exists. Change one of the three, or edit the existing entry.",
                      "code": "CUSTOMER_NAME_EXISTS",
                      "details": {
                        "name": "Muster Handel AG"
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_CUSTOMER_INCOMPLETE`: No customer has this externalRef yet, and making one takes its type, its name, its e-mail address and its address.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_INCOMPLETE": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No customer has this externalRef yet, and making one takes its type, its name, its e-mail address and its address.",
                      "code": "EXT_CUSTOMER_INCOMPLETE",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: type: Invalid enum value. Expected 'business' | 'individual', received 'other'",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "type",
                            "message": "Invalid enum value. Expected 'business' | 'individual', received 'other'"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer",
          "action": "edit"
        },
        "x-mast-also-right": {
          "feature": "Customer",
          "action": "create"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_save_customer"
      },
      "patch": {
        "operationId": "customers.update",
        "tags": [
          "Customers"
        ],
        "summary": "Change a customer",
        "description": "Changes the fields given; a field left out stays as it is.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "description": "`business` for a company, named by `companyName`; `individual` for a person, named by `firstName` and `lastName`.",
                    "type": "string",
                    "enum": [
                      "business",
                      "individual"
                    ]
                  },
                  "email": {
                    "description": "The address invoices and reminders are sent to. Every customer of Mast has one.",
                    "type": "string",
                    "maxLength": 254,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                  },
                  "address": {
                    "description": "The billing address: what the customer's invoices print.",
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200,
                        "description": "Street and number, on one line."
                      },
                      "postalCode": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 20
                      },
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1,
                        "maxLength": 100,
                        "description": "The country's name, as the customer's card in Mast writes it (\"France\", \"Germany\"). Left out, the company's own country."
                      }
                    },
                    "required": [
                      "street",
                      "postalCode",
                      "city"
                    ]
                  },
                  "companyName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "Required for a business."
                  },
                  "firstName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "Required for an individual."
                  },
                  "lastName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "Required for an individual."
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "Mast keeps it in its international form, without spaces (`+41440000000`), and serves it so. Null or an empty string removes it."
                  },
                  "language": {
                    "description": "The language the customer's invoices and reminders are written in. Left out on a create, the company's own.",
                    "type": "string",
                    "enum": [
                      "de",
                      "fr",
                      "it",
                      "en"
                    ]
                  },
                  "vatNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "The customer's VAT number, in its country's format (`CHE-123.456.789 MWST`, `DE123456789`). Null or an empty string removes it."
                  },
                  "registrationNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100,
                    "description": "Its commercial-register number (a UID, or a foreign registry's id). Null or an empty string removes it."
                  },
                  "defaultDiscountPercent": {
                    "description": "The discount Mast holds for this customer, in percent; 0 for none. An invoice takes it only when it says `applyCustomerDefaultDiscount`.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "paymentTermsDays": {
                    "description": "Its net payment terms in whole days, 0 for due on receipt. An invoice that names no terms takes them. 30 when never set.",
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The customer, changed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CUSTOMER_INVALID`: This customer is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This customer is not valid.",
                      "code": "EXT_CUSTOMER_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_CUSTOMER_NOT_FOUND`: No customer of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No customer of the company has this reference.",
                      "code": "EXT_CUSTOMER_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`CUSTOMER_NAME_EXISTS`: If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CUSTOMER_NAME_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "If that customer was made in Mast, give it your reference with `PATCH /ext/customers/by-id/{id}` rather than making a second one.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A customer named \"Muster Handel AG\" with the same billing address and email address already exists. Change one of the three, or edit the existing entry.",
                      "code": "CUSTOMER_NAME_EXISTS",
                      "details": {
                        "name": "Muster Handel AG"
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: type: Invalid enum value. Expected 'business' | 'individual', received 'other'",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "type",
                            "message": "Invalid enum value. Expected 'business' | 'individual', received 'other'"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/crm-1042"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer",
          "action": "edit"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/customers/by-id/{id}": {
      "get": {
        "operationId": "customers.readById",
        "tags": [
          "Customers"
        ],
        "summary": "A customer, by Mast’s id",
        "description": "For a customer made in Mast, which has no `externalRef`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The customer.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_CUSTOMER_NOT_FOUND`: No customer of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No customer of the company has this reference.",
                      "code": "EXT_CUSTOMER_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        }
      },
      "patch": {
        "operationId": "customers.updateById",
        "tags": [
          "Customers"
        ],
        "summary": "Give a customer your reference, by Mast’s id",
        "description": "For a customer that is already in Mast with no `externalRef`, because a person made or imported it there. The call gives it your own id: `PUT /ext/customers/{externalRef}` then finds that customer and changes it, and an invoice can name it (`customerExternalRef`). It also changes the reference a customer holds, and `null` takes it away. The reference it already holds changes nothing. No other field is changed here: once the customer holds your reference, change it by that.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalRef": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$",
                    "description": "Your own id for this customer: from then on it is addressed by it (`/ext/customers/{externalRef}`), and an invoice names it by it (`customerExternalRef`). Unique per company. Null takes away the one it holds."
                  }
                },
                "required": [
                  "externalRef"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The customer, with the reference it now holds.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "400": {
            "description": "`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_CUSTOMER_NOT_FOUND`: No customer of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No customer of the company has this reference.",
                      "code": "EXT_CUSTOMER_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_CUSTOMER_EXISTS`: A customer with this externalRef already exists in the company: update it with PATCH or PUT.\n\n`EXT_CUSTOMER_ARCHIVED`: The customer with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CUSTOMER_EXISTS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A customer with this externalRef already exists in the company: update it with PATCH or PUT.",
                      "code": "EXT_CUSTOMER_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "EXT_CUSTOMER_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The customer with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_CUSTOMER_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: externalRef: Required",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "externalRef",
                            "message": "Required"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer",
          "action": "edit"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/products": {
      "get": {
        "operationId": "products.list",
        "tags": [
          "Products"
        ],
        "summary": "The products changed since a moment",
        "description": "Every product of the company, yours and the ones people made in Mast, oldest change first. A product deleted in Mast drops out of the list.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most: 50 when left out, never more than 100.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of products.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Product",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_products"
      },
      "post": {
        "operationId": "products.create",
        "tags": [
          "Products"
        ],
        "summary": "Make a product",
        "description": "Makes a product under your own id. To make it or change it in one call whatever its state, use `PUT /ext/products/{externalRef}`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalRef": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$",
                    "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "good",
                      "service"
                    ],
                    "description": "`good` for something delivered, `service` for work done."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "The name an invoice line of this product prints."
                  },
                  "unitPrice": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 99999999.99,
                    "description": "The selling price of one unit, without VAT unless an invoice says its prices include it. A line may always name its own."
                  },
                  "code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 50,
                    "description": "The product's own code, printed beside its name. Null removes it."
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 2000,
                    "description": "A note on the product in Mast. Null removes it."
                  },
                  "costPrice": {
                    "description": "What one unit costs the company; 0 when never set.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 99999999.99
                  },
                  "currency": {
                    "description": "The ISO 4217 code its prices are in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency. An invoice line that takes the product's price takes the number as it is, in the invoice's own currency: nothing is converted.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "unit": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 50,
                    "description": "What a quantity counts (`h`, `pcs`, `kg`). Null removes it."
                  },
                  "accountCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 20,
                    "description": "The number of the revenue account, in the company's chart, that a line of this product is booked to. Null removes it."
                  },
                  "vatRateCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 40,
                    "description": "One of the company's VAT codes (`CH_STD`): the rate a line of this product takes when it names none. Null removes it."
                  }
                },
                "required": [
                  "externalRef",
                  "type",
                  "name",
                  "unitPrice"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The product made.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_PRODUCT_INVALID`: This product is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This product is not valid.",
                      "code": "EXT_PRODUCT_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_PRODUCT_EXISTS`: A product with this externalRef already exists in the company: update it with PATCH or PUT.\n\n`EXT_PRODUCT_ARCHIVED`: The product with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_EXISTS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A product with this externalRef already exists in the company: update it with PATCH or PUT.",
                      "code": "EXT_PRODUCT_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "EXT_PRODUCT_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The product with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_PRODUCT_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_PRODUCT_ACCOUNT_UNKNOWN`: No active account of the company's chart has this accountCode.\n\n`EXT_PRODUCT_VAT_RATE_UNKNOWN`: No VAT rate the company sells at today has this vatRateCode.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_ACCOUNT_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No active account of the company's chart has this accountCode.",
                      "code": "EXT_PRODUCT_ACCOUNT_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "EXT_PRODUCT_VAT_RATE_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No VAT rate the company sells at today has this vatRateCode.",
                      "code": "EXT_PRODUCT_VAT_RATE_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: externalRef: Required, type: Required, name: Required, unitPrice: Required",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "externalRef",
                            "message": "Required"
                          },
                          {
                            "field": "type",
                            "message": "Required"
                          },
                          {
                            "field": "name",
                            "message": "Required"
                          },
                          {
                            "field": "unitPrice",
                            "message": "Required"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Product",
          "action": "create"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/products/{externalRef}": {
      "get": {
        "operationId": "products.read",
        "tags": [
          "Products"
        ],
        "summary": "A product, by your reference",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The product.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_PRODUCT_NOT_FOUND`: No product of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No product of the company has this reference.",
                      "code": "EXT_PRODUCT_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Product",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_get_product"
      },
      "put": {
        "operationId": "products.upsert",
        "tags": [
          "Products"
        ],
        "summary": "Make or change a product",
        "description": "When the company has no product under this reference it is made, and the body must then hold what a creation needs (type, name, unit price); else the fields given are changed and the others stay. Safe to repeat.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "description": "`good` for something delivered, `service` for work done.",
                    "type": "string",
                    "enum": [
                      "good",
                      "service"
                    ]
                  },
                  "name": {
                    "description": "The name an invoice line of this product prints.",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "unitPrice": {
                    "description": "The selling price of one unit, without VAT unless an invoice says its prices include it. A line may always name its own.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 99999999.99
                  },
                  "code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 50,
                    "description": "The product's own code, printed beside its name. Null removes it."
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 2000,
                    "description": "A note on the product in Mast. Null removes it."
                  },
                  "costPrice": {
                    "description": "What one unit costs the company; 0 when never set.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 99999999.99
                  },
                  "currency": {
                    "description": "The ISO 4217 code its prices are in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency. An invoice line that takes the product's price takes the number as it is, in the invoice's own currency: nothing is converted.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "unit": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 50,
                    "description": "What a quantity counts (`h`, `pcs`, `kg`). Null removes it."
                  },
                  "accountCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 20,
                    "description": "The number of the revenue account, in the company's chart, that a line of this product is booked to. Null removes it."
                  },
                  "vatRateCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 40,
                    "description": "One of the company's VAT codes (`CH_STD`): the rate a line of this product takes when it names none. Null removes it."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The product, changed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "201": {
            "description": "The reference was new: the product was made.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_PRODUCT_INVALID`: This product is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This product is not valid.",
                      "code": "EXT_PRODUCT_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_PRODUCT_ARCHIVED`: The product with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The product with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_PRODUCT_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_PRODUCT_ACCOUNT_UNKNOWN`: No active account of the company's chart has this accountCode.\n\n`EXT_PRODUCT_VAT_RATE_UNKNOWN`: No VAT rate the company sells at today has this vatRateCode.\n\n`EXT_PRODUCT_INCOMPLETE`: No product has this externalRef yet, and making one takes its type, its name and its unit price.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_ACCOUNT_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No active account of the company's chart has this accountCode.",
                      "code": "EXT_PRODUCT_ACCOUNT_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "EXT_PRODUCT_VAT_RATE_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No VAT rate the company sells at today has this vatRateCode.",
                      "code": "EXT_PRODUCT_VAT_RATE_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "EXT_PRODUCT_INCOMPLETE": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No product has this externalRef yet, and making one takes its type, its name and its unit price.",
                      "code": "EXT_PRODUCT_INCOMPLETE",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: type: Invalid enum value. Expected 'good' | 'service', received 'other'",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "type",
                            "message": "Invalid enum value. Expected 'good' | 'service', received 'other'"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Product",
          "action": "edit"
        },
        "x-mast-also-right": {
          "feature": "Product",
          "action": "create"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_save_product"
      },
      "patch": {
        "operationId": "products.update",
        "tags": [
          "Products"
        ],
        "summary": "Change a product",
        "description": "Changes the fields given; a field left out stays as it is.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "description": "`good` for something delivered, `service` for work done.",
                    "type": "string",
                    "enum": [
                      "good",
                      "service"
                    ]
                  },
                  "name": {
                    "description": "The name an invoice line of this product prints.",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "unitPrice": {
                    "description": "The selling price of one unit, without VAT unless an invoice says its prices include it. A line may always name its own.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 99999999.99
                  },
                  "code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 50,
                    "description": "The product's own code, printed beside its name. Null removes it."
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 2000,
                    "description": "A note on the product in Mast. Null removes it."
                  },
                  "costPrice": {
                    "description": "What one unit costs the company; 0 when never set.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 99999999.99
                  },
                  "currency": {
                    "description": "The ISO 4217 code its prices are in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency. An invoice line that takes the product's price takes the number as it is, in the invoice's own currency: nothing is converted.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "unit": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 50,
                    "description": "What a quantity counts (`h`, `pcs`, `kg`). Null removes it."
                  },
                  "accountCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 20,
                    "description": "The number of the revenue account, in the company's chart, that a line of this product is booked to. Null removes it."
                  },
                  "vatRateCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 40,
                    "description": "One of the company's VAT codes (`CH_STD`): the rate a line of this product takes when it names none. Null removes it."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The product, changed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_PRODUCT_INVALID`: This product is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This product is not valid.",
                      "code": "EXT_PRODUCT_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_PRODUCT_NOT_FOUND`: No product of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No product of the company has this reference.",
                      "code": "EXT_PRODUCT_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_PRODUCT_ACCOUNT_UNKNOWN`: No active account of the company's chart has this accountCode.\n\n`EXT_PRODUCT_VAT_RATE_UNKNOWN`: No VAT rate the company sells at today has this vatRateCode.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_ACCOUNT_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No active account of the company's chart has this accountCode.",
                      "code": "EXT_PRODUCT_ACCOUNT_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "EXT_PRODUCT_VAT_RATE_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No VAT rate the company sells at today has this vatRateCode.",
                      "code": "EXT_PRODUCT_VAT_RATE_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: type: Invalid enum value. Expected 'good' | 'service', received 'other'",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "type",
                            "message": "Invalid enum value. Expected 'good' | 'service', received 'other'"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/sku-conseil"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Product",
          "action": "edit"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/products/by-id/{id}": {
      "get": {
        "operationId": "products.readById",
        "tags": [
          "Products"
        ],
        "summary": "A product, by Mast’s id",
        "description": "For a product made in Mast, which has no `externalRef`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The product.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_PRODUCT_NOT_FOUND`: No product of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No product of the company has this reference.",
                      "code": "EXT_PRODUCT_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Product",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        }
      },
      "patch": {
        "operationId": "products.updateById",
        "tags": [
          "Products"
        ],
        "summary": "Give a product your reference, by Mast’s id",
        "description": "For a product that is already in Mast with no `externalRef`, because a person made or imported it there. The call gives it your own id: `PUT /ext/products/{externalRef}` then finds that product and changes it, and an invoice line can name it (`productExternalRef`). It also changes the reference a product holds, and `null` takes it away. The reference it already holds changes nothing. No other field is changed here: once the product holds your reference, change it by that.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalRef": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$",
                    "description": "Your own id for this product: from then on it is addressed by it (`/ext/products/{externalRef}`), and an invoice line names it by it (`productExternalRef`). Unique per company. Null takes away the one it holds."
                  }
                },
                "required": [
                  "externalRef"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The product, with the reference it now holds.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "400": {
            "description": "`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_PRODUCT_NOT_FOUND`: No product of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No product of the company has this reference.",
                      "code": "EXT_PRODUCT_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_PRODUCT_EXISTS`: A product with this externalRef already exists in the company: update it with PATCH or PUT.\n\n`EXT_PRODUCT_ARCHIVED`: The product with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_PRODUCT_EXISTS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A product with this externalRef already exists in the company: update it with PATCH or PUT.",
                      "code": "EXT_PRODUCT_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "EXT_PRODUCT_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The product with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_PRODUCT_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: externalRef: Required",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "externalRef",
                            "message": "Required"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/products/by-id/cmwo42a1j00a8xtuq6v3s9kpd"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Product",
          "action": "edit"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/invoices": {
      "get": {
        "operationId": "invoices.list",
        "tags": [
          "Invoices"
        ],
        "summary": "The invoices changed since a moment",
        "description": "Every invoice of the company, yours and the ones people made in Mast, oldest change first, by `status` when asked. `include=lines` adds each invoice’s lines. An invoice that becomes overdue does not change, so a read by `updatedSince` does not serve it again for that: `overdue` is judged on the day of the read. A page ends early past 2,000 lines, counted whether or not `include=lines` asks for them (the figures are worked out from them), never inside a document: follow `nextCursor`.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most: 50 when left out, never more than 100.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "`lines`: each document comes with its lines. Left out, `lines` is null and the page is lighter.",
            "schema": {
              "type": "string",
              "enum": [
                "lines"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only the documents in one of these states, separated by commas: draft, open, overdue, partially_paid, paid, cancelled, paid_in_provider, refunded_in_provider, paid_outside_provider.",
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "maxItems": 500,
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of invoices.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Invoice"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_invoices"
      },
      "post": {
        "operationId": "invoices.create",
        "tags": [
          "Invoices"
        ],
        "summary": "Make a draft invoice",
        "description": "Makes a **draft** for one of your customers, under your own id. A draft has no official number and no journal entry: it takes both when it is issued (`…/validate`, or `…/send`). A line names a product by `productExternalRef` and takes its name, price and VAT rate where it gives none of its own, or is free text with its own price. Mast applies no discount the call does not name: give the line’s `discountPercent`, the document’s `discountPercent` or `discountAmount`, or ask for the customer’s default with `applyCustomerDefaultDiscount`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "issueDate": {
                    "description": "The day the invoice is dated (YYYY-MM-DD). Left out on a create, today.",
                    "type": "string"
                  },
                  "dueDate": {
                    "description": "The day it is due (YYYY-MM-DD). Left out or null, the issue date plus the payment terms.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "paymentTermsDays": {
                    "description": "The net payment terms in days, 0 for due on receipt. Left out on a create, the customer's own terms.",
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 365
                  },
                  "paymentTermsText": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 500,
                    "description": "The payment terms in words, printed on the invoice."
                  },
                  "supplyPeriodStart": {
                    "description": "The time of supply, when it is not the issue date: its first day (YYYY-MM-DD). It decides the VAT rate and is printed.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "supplyPeriodEnd": {
                    "description": "The last day of the supply period (YYYY-MM-DD); left out, its first day.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "currency": {
                    "description": "The ISO 4217 code the invoice is in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "language": {
                    "description": "The language the invoice is written in. Left out on a create, the customer's language.",
                    "type": "string",
                    "enum": [
                      "de",
                      "fr",
                      "it",
                      "en"
                    ]
                  },
                  "reference": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 200,
                    "description": "Your customer's own reference (an order number), printed on the invoice."
                  },
                  "title": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 200,
                    "description": "A title printed above the lines."
                  },
                  "introText": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 5000,
                    "description": "A text printed between the title and the lines."
                  },
                  "notes": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 5000,
                    "description": "A text printed under the totals."
                  },
                  "footerText": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 5000,
                    "description": "A text printed at the foot of the invoice."
                  },
                  "priceIncludesVat": {
                    "description": "True when the unit prices sent include VAT, which Mast then backs out of each line. False when left out.",
                    "type": "boolean"
                  },
                  "discountPercent": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 100,
                    "description": "A discount on the whole invoice, in percent, taken after each line's own. Not beside `discountAmount`."
                  },
                  "discountAmount": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 999999999999.99,
                    "description": "A discount on the whole invoice, as an amount of its currency. One above what the lines come to is not refused: it is taken as the whole of them, the invoice comes to 0.00, and it can be issued so. Not beside `discountPercent`."
                  },
                  "externalRef": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$",
                    "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
                  },
                  "customerExternalRef": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$",
                    "description": "The externalRef of the customer the invoice is for."
                  },
                  "applyCustomerDefaultDiscount": {
                    "description": "True: the draft takes the customer's default discount, when the call names no discount of its own. Left out, Mast applies no discount the call did not ask for.",
                    "type": "boolean"
                  },
                  "lines": {
                    "minItems": 1,
                    "maxItems": 1000,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 2000,
                          "description": "The line's words. Required unless the line names a product, whose name it then takes; beside a product, they follow its name."
                        },
                        "quantity": {
                          "type": "number",
                          "minimum": -999999999999.99,
                          "maximum": 999999999999.99,
                          "description": "How many units the line bills; below zero for a line that takes something off. Never zero. Times the unit price, at most 999999999999.99 either way."
                        },
                        "unit": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 20,
                          "description": "What the quantity counts (`h`, `pcs`). Left out, the product's unit, else `pcs`."
                        },
                        "unitPrice": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": 0,
                          "maximum": 999999999999.99,
                          "description": "The price of one unit, without VAT unless the invoice says `priceIncludesVat`. Required unless the line names a product, whose price it then takes as the number it is, in the invoice's currency, whatever the product's currency (nothing is converted): a price agreed with this customer is simply the price sent."
                        },
                        "discountPercent": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": 0,
                          "maximum": 100,
                          "description": "The line's own discount, in percent."
                        },
                        "vatRatePercent": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": 0,
                          "maximum": 100,
                          "description": "The line's VAT rate, in percent (8.1, 2.6, 0). May be left out when `vatRateCode` names a rate, or when the line's product has one."
                        },
                        "vatRateCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 40,
                          "description": "One of the company's VAT codes, as its VAT settings list them (`CH_STD`, `EXP_GOODS`): the line takes that rate. A `vatRatePercent` beside it must agree."
                        },
                        "productExternalRef": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 100,
                          "pattern": "^[^\u0000]*$",
                          "description": "The externalRef of a product: the line is that product's, takes its name, price, unit and VAT rate where it names none, and is booked to its revenue account. Its price is taken as the number it is, in the invoice's currency: a product priced 100 in EUR gives 100.00 on an invoice in CHF, so give a line of an invoice in another currency its own `unitPrice`."
                        },
                        "productCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 100,
                          "description": "A product code to print on the line. Left out, the product's own."
                        },
                        "revenueAccountCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 20,
                          "description": "The number of the revenue account, in the company's chart, this line is booked to. Left out, the product's, else the company's default."
                        },
                        "costCenterCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 50,
                          "description": "The code of one of the company's cost centres, which the line's revenue is filed under."
                        },
                        "comment": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "maxLength": 2000,
                          "description": "A note printed under the line."
                        },
                        "supplyPeriodStart": {
                          "description": "When this line was supplied, if not when the invoice says: its first day (YYYY-MM-DD).",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "supplyPeriodEnd": {
                          "description": "The last day of this line's own supply period (YYYY-MM-DD); left out, its first day.",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "quantity"
                      ]
                    },
                    "description": "The lines, in the order the invoice prints them: one at least."
                  }
                },
                "required": [
                  "externalRef",
                  "customerExternalRef",
                  "lines"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The draft, with its lines and its totals.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_INVOICE_INVALID`: This invoice is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`INVOICE_TOTAL_NEGATIVE`: The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This invoice is not valid.",
                      "code": "EXT_INVOICE_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "INVOICE_TOTAL_NEGATIVE": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects.",
                    "value": {
                      "statusCode": 400,
                      "error": "InvoiceTotalNegativeError",
                      "message": "Invoice has a negative total (-108.10). To take an amount back from a customer, issue a credit note on the invoice it corrects.",
                      "code": "INVOICE_TOTAL_NEGATIVE",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_INVOICE_EXISTS`: An invoice with this externalRef already exists in the company.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_EXISTS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "An invoice with this externalRef already exists in the company.",
                      "code": "EXT_INVOICE_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_INVOICE_CUSTOMER_UNKNOWN`: No customer has this customerExternalRef in the company: make it first (PUT /ext/customers/{externalRef}).\n\n`EXT_INVOICE_PRODUCT_UNKNOWN`: No product has this productExternalRef in the company: make it first (PUT /ext/products/{externalRef}).\n\n`EXT_INVOICE_VAT_RATE_UNKNOWN`: No VAT rate the company sells at on the invoice's day has this vatRateCode: name one of its VAT codes, or give vatRatePercent.\n\n`EXT_INVOICE_VAT_RATE_MISMATCH`: vatRatePercent is not the rate vatRateCode names: send one of the two, or the two in agreement.\n\n`EXT_INVOICE_VAT_RATE_MISSING`: This line names no VAT rate and its product has none of its own: give vatRatePercent or vatRateCode.\n\n`EXT_INVOICE_COST_CENTER_UNKNOWN`: No cost centre of the company has this costCenterCode.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_CUSTOMER_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No customer has this customerExternalRef in the company: make it first (PUT /ext/customers/{externalRef}).",
                      "code": "EXT_INVOICE_CUSTOMER_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "EXT_INVOICE_PRODUCT_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No product has this productExternalRef in the company: make it first (PUT /ext/products/{externalRef}).",
                      "code": "EXT_INVOICE_PRODUCT_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "EXT_INVOICE_VAT_RATE_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No VAT rate the company sells at on the invoice's day has this vatRateCode: name one of its VAT codes, or give vatRatePercent.",
                      "code": "EXT_INVOICE_VAT_RATE_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "EXT_INVOICE_VAT_RATE_MISMATCH": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "vatRatePercent is not the rate vatRateCode names: send one of the two, or the two in agreement.",
                      "code": "EXT_INVOICE_VAT_RATE_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "EXT_INVOICE_VAT_RATE_MISSING": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This line names no VAT rate and its product has none of its own: give vatRatePercent or vatRateCode.",
                      "code": "EXT_INVOICE_VAT_RATE_MISSING",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "EXT_INVOICE_COST_CENTER_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No cost centre of the company has this costCenterCode.",
                      "code": "EXT_INVOICE_COST_CENTER_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: externalRef: Required, customerExternalRef: Required, lines: Required",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "externalRef",
                            "message": "Required"
                          },
                          {
                            "field": "customerExternalRef",
                            "message": "Required"
                          },
                          {
                            "field": "lines",
                            "message": "Required"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "create"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_create_invoice_draft"
      }
    },
    "/ext/invoices/{externalRef}": {
      "get": {
        "operationId": "invoices.read",
        "tags": [
          "Invoices"
        ],
        "summary": "An invoice with its lines, by your reference",
        "description": "Its number, its state, what it bills line by line and what is still owed.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The invoice, with its lines.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_get_invoice"
      },
      "patch": {
        "operationId": "invoices.update",
        "tags": [
          "Invoices"
        ],
        "summary": "Change a draft",
        "description": "While the invoice is a draft: the fields given replace the draft’s, and `lines` given replace every line. A change of discount or of `priceIncludesVat` reprices the invoice, so it comes with the lines. A change that brings the total below zero is taken, and the draft is then refused when it is issued (`INVOICE_TOTAL_NEGATIVE`). An issued invoice is not changed: it is corrected by a credit note.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "issueDate": {
                    "description": "The day the invoice is dated (YYYY-MM-DD). Left out on a create, today.",
                    "type": "string"
                  },
                  "dueDate": {
                    "description": "The day it is due (YYYY-MM-DD). Left out or null, the issue date plus the payment terms.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "paymentTermsDays": {
                    "description": "The net payment terms in days, 0 for due on receipt. Left out on a create, the customer's own terms.",
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 365
                  },
                  "paymentTermsText": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 500,
                    "description": "The payment terms in words, printed on the invoice."
                  },
                  "supplyPeriodStart": {
                    "description": "The time of supply, when it is not the issue date: its first day (YYYY-MM-DD). It decides the VAT rate and is printed.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "supplyPeriodEnd": {
                    "description": "The last day of the supply period (YYYY-MM-DD); left out, its first day.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "currency": {
                    "description": "The ISO 4217 code the invoice is in, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out on a create, the company's base currency.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "language": {
                    "description": "The language the invoice is written in. Left out on a create, the customer's language.",
                    "type": "string",
                    "enum": [
                      "de",
                      "fr",
                      "it",
                      "en"
                    ]
                  },
                  "reference": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 200,
                    "description": "Your customer's own reference (an order number), printed on the invoice."
                  },
                  "title": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 200,
                    "description": "A title printed above the lines."
                  },
                  "introText": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 5000,
                    "description": "A text printed between the title and the lines."
                  },
                  "notes": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 5000,
                    "description": "A text printed under the totals."
                  },
                  "footerText": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 5000,
                    "description": "A text printed at the foot of the invoice."
                  },
                  "priceIncludesVat": {
                    "description": "True when the unit prices sent include VAT, which Mast then backs out of each line. False when left out.",
                    "type": "boolean"
                  },
                  "discountPercent": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 100,
                    "description": "A discount on the whole invoice, in percent, taken after each line's own. Not beside `discountAmount`."
                  },
                  "discountAmount": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 999999999999.99,
                    "description": "A discount on the whole invoice, as an amount of its currency. One above what the lines come to is not refused: it is taken as the whole of them, the invoice comes to 0.00, and it can be issued so. Not beside `discountPercent`."
                  },
                  "customerExternalRef": {
                    "description": "The externalRef of another customer to bill the draft to.",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$"
                  },
                  "lines": {
                    "description": "New lines, which replace every line of the draft. A change of discount or of `priceIncludesVat` comes with them.",
                    "minItems": 1,
                    "maxItems": 1000,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 2000,
                          "description": "The line's words. Required unless the line names a product, whose name it then takes; beside a product, they follow its name."
                        },
                        "quantity": {
                          "type": "number",
                          "minimum": -999999999999.99,
                          "maximum": 999999999999.99,
                          "description": "How many units the line bills; below zero for a line that takes something off. Never zero. Times the unit price, at most 999999999999.99 either way."
                        },
                        "unit": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 20,
                          "description": "What the quantity counts (`h`, `pcs`). Left out, the product's unit, else `pcs`."
                        },
                        "unitPrice": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": 0,
                          "maximum": 999999999999.99,
                          "description": "The price of one unit, without VAT unless the invoice says `priceIncludesVat`. Required unless the line names a product, whose price it then takes as the number it is, in the invoice's currency, whatever the product's currency (nothing is converted): a price agreed with this customer is simply the price sent."
                        },
                        "discountPercent": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": 0,
                          "maximum": 100,
                          "description": "The line's own discount, in percent."
                        },
                        "vatRatePercent": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": 0,
                          "maximum": 100,
                          "description": "The line's VAT rate, in percent (8.1, 2.6, 0). May be left out when `vatRateCode` names a rate, or when the line's product has one."
                        },
                        "vatRateCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 40,
                          "description": "One of the company's VAT codes, as its VAT settings list them (`CH_STD`, `EXP_GOODS`): the line takes that rate. A `vatRatePercent` beside it must agree."
                        },
                        "productExternalRef": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 100,
                          "pattern": "^[^\u0000]*$",
                          "description": "The externalRef of a product: the line is that product's, takes its name, price, unit and VAT rate where it names none, and is booked to its revenue account. Its price is taken as the number it is, in the invoice's currency: a product priced 100 in EUR gives 100.00 on an invoice in CHF, so give a line of an invoice in another currency its own `unitPrice`."
                        },
                        "productCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 100,
                          "description": "A product code to print on the line. Left out, the product's own."
                        },
                        "revenueAccountCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 20,
                          "description": "The number of the revenue account, in the company's chart, this line is booked to. Left out, the product's, else the company's default."
                        },
                        "costCenterCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1,
                          "maxLength": 50,
                          "description": "The code of one of the company's cost centres, which the line's revenue is filed under."
                        },
                        "comment": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "maxLength": 2000,
                          "description": "A note printed under the line."
                        },
                        "supplyPeriodStart": {
                          "description": "When this line was supplied, if not when the invoice says: its first day (YYYY-MM-DD).",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "supplyPeriodEnd": {
                          "description": "The last day of this line's own supply period (YYYY-MM-DD); left out, its first day.",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "quantity"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The draft, changed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_INVOICE_INVALID`: This invoice is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This invoice is not valid.",
                      "code": "EXT_INVOICE_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_INVOICE_NOT_DRAFT`: This invoice is issued: only a draft is changed or deleted. An issued invoice is corrected by a credit note.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_DRAFT": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This invoice is issued: only a draft is changed or deleted. An issued invoice is corrected by a credit note.",
                      "code": "EXT_INVOICE_NOT_DRAFT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_INVOICE_LINES_REQUIRED`: A change of discount or of priceIncludesVat reprices the invoice: send its lines with it.\n\n`EXT_INVOICE_CUSTOMER_UNKNOWN`: No customer has this customerExternalRef in the company: make it first (PUT /ext/customers/{externalRef}).\n\n`EXT_INVOICE_PRODUCT_UNKNOWN`: No product has this productExternalRef in the company: make it first (PUT /ext/products/{externalRef}).\n\n`EXT_INVOICE_VAT_RATE_UNKNOWN`: No VAT rate the company sells at on the invoice's day has this vatRateCode: name one of its VAT codes, or give vatRatePercent.\n\n`EXT_INVOICE_VAT_RATE_MISMATCH`: vatRatePercent is not the rate vatRateCode names: send one of the two, or the two in agreement.\n\n`EXT_INVOICE_VAT_RATE_MISSING`: This line names no VAT rate and its product has none of its own: give vatRatePercent or vatRateCode.\n\n`EXT_INVOICE_COST_CENTER_UNKNOWN`: No cost centre of the company has this costCenterCode.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_LINES_REQUIRED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "A change of discount or of priceIncludesVat reprices the invoice: send its lines with it.",
                      "code": "EXT_INVOICE_LINES_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "EXT_INVOICE_CUSTOMER_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No customer has this customerExternalRef in the company: make it first (PUT /ext/customers/{externalRef}).",
                      "code": "EXT_INVOICE_CUSTOMER_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "EXT_INVOICE_PRODUCT_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No product has this productExternalRef in the company: make it first (PUT /ext/products/{externalRef}).",
                      "code": "EXT_INVOICE_PRODUCT_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "EXT_INVOICE_VAT_RATE_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No VAT rate the company sells at on the invoice's day has this vatRateCode: name one of its VAT codes, or give vatRatePercent.",
                      "code": "EXT_INVOICE_VAT_RATE_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "EXT_INVOICE_VAT_RATE_MISMATCH": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "vatRatePercent is not the rate vatRateCode names: send one of the two, or the two in agreement.",
                      "code": "EXT_INVOICE_VAT_RATE_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "EXT_INVOICE_VAT_RATE_MISSING": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This line names no VAT rate and its product has none of its own: give vatRatePercent or vatRateCode.",
                      "code": "EXT_INVOICE_VAT_RATE_MISSING",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "EXT_INVOICE_COST_CENTER_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No cost centre of the company has this costCenterCode.",
                      "code": "EXT_INVOICE_COST_CENTER_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: issueDate: Expected string, received number",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "issueDate",
                            "message": "Expected string, received number"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "edit"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_update_invoice_draft"
      },
      "delete": {
        "operationId": "invoices.delete",
        "tags": [
          "Invoices"
        ],
        "summary": "Drop a draft",
        "description": "Deletes a draft, whose reference is then free again. An issued invoice is never deleted.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "204": {
            "description": "Dropped.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            }
          },
          "400": {
            "description": "`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_INVOICE_NOT_DRAFT`: This invoice is issued: only a draft is changed or deleted. An issued invoice is corrected by a credit note.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_DRAFT": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This invoice is issued: only a draft is changed or deleted. An issued invoice is corrected by a credit note.",
                      "code": "EXT_INVOICE_NOT_DRAFT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/%20"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "delete"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_delete_invoice_draft"
      }
    },
    "/ext/invoices/{externalRef}/validate": {
      "post": {
        "operationId": "invoices.validate",
        "tags": [
          "Invoices"
        ],
        "summary": "Issue a draft",
        "description": "Issues the invoice: it takes its official number in the company’s series and its journal entry, written under the key’s name. This cannot be undone by the API: an issued invoice is corrected by a credit note in Mast. Send an `Idempotency-Key`. The books’ own rules can refuse it (a closed period, an account the company has not mapped), with the code the app itself answers.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "The invoice, issued.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "description": "`INVOICE_TOTAL_NEGATIVE`: The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVOICE_TOTAL_NEGATIVE": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects.",
                    "value": {
                      "statusCode": 400,
                      "error": "InvoiceTotalNegativeError",
                      "message": "Invoice has a negative total (-108.10). To take an amount back from a customer, issue a credit note on the invoice it corrects.",
                      "code": "INVOICE_TOTAL_NEGATIVE",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/%20/validate"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/validate"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "post"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/invoices/{externalRef}/send": {
      "post": {
        "operationId": "invoices.send",
        "tags": [
          "Invoices"
        ],
        "summary": "E-mail the invoice to the customer",
        "description": "Sends the invoice with its PDF by the sender the company chose under Settings › Email Configuration (its own Microsoft 365 mailbox, or, where the account is offered it, Mast in the company’s name), to the customer’s address unless `recipient` names another, in the words of the company’s « invoice sent » template unless `subject` and `message` are given. A draft is issued on its way out, so the call asks the right to issue. Everything that can refuse the send is checked before anything is issued. A send to the same recipients within a minute of one that went out sends nothing more and answers `deduplicated: true`; one made while another send of the invoice is still running is refused. Later, a send goes out again: send an `Idempotency-Key`.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "recipient": {
                    "description": "The address the invoice goes to. Left out, the customer's e-mail address in Mast.",
                    "type": "string",
                    "maxLength": 320,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                  },
                  "ccRecipient": {
                    "description": "An address that receives a copy.",
                    "type": "string",
                    "maxLength": 320,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                  },
                  "subject": {
                    "description": "The e-mail's subject. Left out, the subject of the company's « invoice sent » template, in the customer's language.",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 300
                  },
                  "message": {
                    "description": "The e-mail's text, plain, its line breaks kept. Left out, the text of the company's « invoice sent » template.",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 20000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The invoice as it stands after the send, and who it went to.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceSendResult"
                }
              }
            }
          },
          "400": {
            "description": "`INVOICE_CANCELLED_CANNOT_BE_SENT`: This invoice can no longer be sent or recorded as sent. Its cancellation reversed the journal entry, so nothing is owed on it.\n\n`INVOICE_TOTAL_NEGATIVE`: The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVOICE_CANCELLED_CANNOT_BE_SENT": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This invoice can no longer be sent or recorded as sent. Its cancellation reversed the journal entry, so nothing is owed on it.",
                      "code": "INVOICE_CANCELLED_CANNOT_BE_SENT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "INVOICE_TOTAL_NEGATIVE": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The lines and the discounts come to less than zero, and an invoice bills. To take an amount back from a customer, make a credit note in Mast on the invoice it corrects.",
                    "value": {
                      "statusCode": 400,
                      "error": "InvoiceTotalNegativeError",
                      "message": "Invoice has a negative total (-108.10). To take an amount back from a customer, issue a credit note on the invoice it corrects.",
                      "code": "INVOICE_TOTAL_NEGATIVE",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`INVOICE_EMAIL_SENDING_DISABLED_YOUR_ORGANIZATION_SETTINGS`: Invoice email sending is disabled in your organization settings.\n\n`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVOICE_EMAIL_SENDING_DISABLED_YOUR_ORGANIZATION_SETTINGS": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Invoice email sending is disabled in your organization settings.",
                      "code": "INVOICE_EMAIL_SENDING_DISABLED_YOUR_ORGANIZATION_SETTINGS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`INVOICE_SEND_IN_FLIGHT`: This invoice is already being sent — wait for the send in progress to finish.\n\n`EMAIL_NO_SENDER_SET_UP`: This company cannot send e-mail yet. Under Settings > Email Configuration, connect a Microsoft 365 mailbox, or let Mast send in the company's name.\n\n`EMAIL_MAST_SENDER_NOT_AVAILABLE`: Sending by Mast in the company's name is not open for this account. Connect a Microsoft 365 mailbox under Settings > Email Configuration, or ask Mast to open it.\n\n`EMAIL_MAST_SENDER_DEMO_ACCOUNT`: A demo or test account sends no real e-mail, so Mast cannot send its documents.\n\n`EMAIL_MAST_SENDER_NO_REPLY_ADDRESS`: Mast sends in the company's name only once a reply address is set, under Settings > Email Configuration.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVOICE_SEND_IN_FLIGHT": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This invoice is already being sent — wait for the send in progress to finish.",
                      "code": "INVOICE_SEND_IN_FLIGHT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "EMAIL_NO_SENDER_SET_UP": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This company cannot send e-mail yet. Under Settings > Email Configuration, connect a Microsoft 365 mailbox, or let Mast send in the company's name.",
                      "code": "EMAIL_NO_SENDER_SET_UP",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "EMAIL_MAST_SENDER_NOT_AVAILABLE": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "Sending by Mast in the company's name is not open for this account. Connect a Microsoft 365 mailbox under Settings > Email Configuration, or ask Mast to open it.",
                      "code": "EMAIL_MAST_SENDER_NOT_AVAILABLE",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "EMAIL_MAST_SENDER_DEMO_ACCOUNT": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A demo or test account sends no real e-mail, so Mast cannot send its documents.",
                      "code": "EMAIL_MAST_SENDER_DEMO_ACCOUNT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "EMAIL_MAST_SENDER_NO_REPLY_ADDRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "Mast sends in the company's name only once a reply address is set, under Settings > Email Configuration.",
                      "code": "EMAIL_MAST_SENDER_NO_REPLY_ADDRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_INVOICE_NO_RECIPIENT`: The customer has no e-mail address in Mast: name the recipient.\n\n`EXT_INVOICE_EMAIL_TEMPLATE_MISSING`: The company has no active « invoice sent » e-mail template: give the subject and the message.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NO_RECIPIENT": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "The customer has no e-mail address in Mast: name the recipient.",
                      "code": "EXT_INVOICE_NO_RECIPIENT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "EXT_INVOICE_EMAIL_TEMPLATE_MISSING": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "The company has no active « invoice sent » e-mail template: give the subject and the message.",
                      "code": "EXT_INVOICE_EMAIL_TEMPLATE_MISSING",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: recipient: Expected string, received number",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "recipient",
                            "message": "Expected string, received number"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`EMAIL_MAST_SENDER_DAILY_LIMIT`: Mast has sent the number of e-mails it sends for one company in a day. Sending resumes tomorrow.\n\n`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EMAIL_MAST_SENDER_DAILY_LIMIT": {
                    "value": {
                      "statusCode": 429,
                      "error": "HttpException",
                      "message": "Mast has sent the number of e-mails it sends for one company in a day. Sending resumes tomorrow.",
                      "code": "EMAIL_MAST_SENDER_DAILY_LIMIT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  },
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "`EXT_INVOICE_SEND_FAILED`: The company's mailbox did not send the e-mail. What the mailbox answered is not passed on: try again later, or send the PDF yourself.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_SEND_FAILED": {
                    "description": "What the mailbox answered is not passed on: try again later, or send the PDF yourself.",
                    "value": {
                      "statusCode": 502,
                      "error": "BadGatewayException",
                      "message": "The company's mailbox did not send the e-mail.",
                      "code": "EXT_INVOICE_SEND_FAILED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "`EMAIL_NO_ACCOUNT_CONNECTED`: No email account connected. Please connect your Microsoft 365 mailbox in Settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EMAIL_NO_ACCOUNT_CONNECTED": {
                    "value": {
                      "statusCode": 503,
                      "error": "ServiceUnavailableException",
                      "message": "No email account connected. Please connect your Microsoft 365 mailbox in Settings.",
                      "code": "EMAIL_NO_ACCOUNT_CONNECTED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/send"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "post"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/invoices/{externalRef}/pdf": {
      "get": {
        "operationId": "invoices.pdf",
        "tags": [
          "Invoices"
        ],
        "summary": "The invoice as a PDF",
        "description": "The document as the customer receives it, with its QR-bill where the company issues one. A key gets one PDF at a time: a call while a PDF it asked for is still being made, or while Mast makes as many PDFs for the API as it makes at once, is answered `429 RATE_LIMITED` with `Retry-After`.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The PDF file.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/%20/pdf"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: A PDF this key asked for is still being made, and a key gets one PDF at a time. Wait for the seconds Retry-After gives, then call again.\n\n`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "A PDF this key asked for is still being made, and a key gets one PDF at a time. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  },
                  "RATE_LIMITED (2)": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/bo-2026-0457/pdf"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ_LIMITED",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/invoices/by-id/{id}": {
      "get": {
        "operationId": "invoices.readById",
        "tags": [
          "Invoices"
        ],
        "summary": "An invoice with its lines, by Mast’s id",
        "description": "For an invoice made in Mast, which has no `externalRef`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The invoice, with its lines.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_get_invoice_by_id"
      }
    },
    "/ext/invoices/by-id/{id}/pdf": {
      "get": {
        "operationId": "invoices.pdfById",
        "tags": [
          "Invoices"
        ],
        "summary": "The PDF of an invoice, by Mast’s id",
        "description": "A key gets one PDF at a time: a call while a PDF it asked for is still being made, or while Mast makes as many PDFs for the API as it makes at once, is answered `429 RATE_LIMITED` with `Retry-After`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The PDF file.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/%20/pdf"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: A PDF this key asked for is still being made, and a key gets one PDF at a time. Wait for the seconds Retry-After gives, then call again.\n\n`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "A PDF this key asked for is still being made, and a key gets one PDF at a time. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  },
                  "RATE_LIMITED (2)": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/invoices/by-id/cmwnsw2sf00a76muqm4kto1cu/pdf"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Invoices",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ_LIMITED",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/credit-notes": {
      "get": {
        "operationId": "credit-notes.list",
        "tags": [
          "Credit notes"
        ],
        "summary": "The credit notes changed since a moment",
        "description": "The company’s credit notes, oldest change first, by `status` when asked, with their lines on `include=lines`. Their amounts are below zero, so invoices and credit notes add up to what was invoiced. Credit notes are made in Mast; the API reads them. A page ends early past 2,000 lines, counted whether or not `include=lines` asks for them (the figures are worked out from them), never inside a document: follow `nextCursor`.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most: 50 when left out, never more than 100.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "`lines`: each document comes with its lines. Left out, `lines` is null and the page is lighter.",
            "schema": {
              "type": "string",
              "enum": [
                "lines"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only the documents in one of these states, separated by commas: draft, open, paid, cancelled.",
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "maxItems": 500,
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of credit notes.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CreditNote"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Credit Notes",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_credit_notes"
      }
    },
    "/ext/credit-notes/{externalRef}": {
      "get": {
        "operationId": "credit-notes.read",
        "tags": [
          "Credit notes"
        ],
        "summary": "A credit note with its lines, by your reference",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The credit note, with its lines.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditNote"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_CREDIT_NOTE_NOT_FOUND`: No credit note of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CREDIT_NOTE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No credit note of the company has this reference.",
                      "code": "EXT_CREDIT_NOTE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/bo-cn-2026-0012"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Credit Notes",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        }
      }
    },
    "/ext/credit-notes/by-id/{id}": {
      "get": {
        "operationId": "credit-notes.readById",
        "tags": [
          "Credit notes"
        ],
        "summary": "A credit note with its lines, by Mast’s id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The credit note, with its lines.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditNote"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_CREDIT_NOTE_NOT_FOUND`: No credit note of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CREDIT_NOTE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No credit note of the company has this reference.",
                      "code": "EXT_CREDIT_NOTE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/credit-notes/by-id/cmwnt0b7q00b26muqk8x1ve3r"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Customer Credit Notes",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_get_credit_note_by_id"
      }
    },
    "/ext/payments": {
      "get": {
        "operationId": "payments.list",
        "tags": [
          "Payments"
        ],
        "summary": "The payments received, changed since a moment",
        "description": "What customers paid against invoices, one row per payment: its day, its amount, its invoice, how it was recorded. `invoiceId` or `invoiceExternalRef` narrows the read to one invoice. A payment cancelled in Mast drops out of the list.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant with its offset (`2026-11-18T08:00:00Z`): only what changed at or after it. Left out, everything.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `nextCursor` of the page before, to read the next one; null there means the list is read to its end. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most: 50 when left out, never more than 100.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "invoiceId",
            "in": "query",
            "required": false,
            "description": "Only the payments of this invoice, by Mast's id of it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$"
            }
          },
          {
            "name": "invoiceExternalRef",
            "in": "query",
            "required": false,
            "description": "Only the payments of this invoice, by your own reference of it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of payments.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_INVOICE_NOT_FOUND`: No invoice of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_INVOICE_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No invoice of the company has this reference.",
                      "code": "EXT_INVOICE_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/payments"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Cash Allocation",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_payments"
      }
    },
    "/ext/accounts": {
      "get": {
        "operationId": "accounts.list",
        "tags": [
          "Accounting"
        ],
        "summary": "The chart of accounts",
        "description": "The accounts and headings of the chart changed since a moment, oldest change first. A small chart fits one or two pages.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the accounts and headings changed at or after it are served, oldest change first. Left out: all of them.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most, 1 to 100. Left out: 50.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of accounts.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Account"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/accounts"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Chart of Accounts",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_accounts"
      }
    },
    "/ext/journal-entries": {
      "get": {
        "operationId": "journal-entries.list",
        "tags": [
          "Accounting"
        ],
        "summary": "Journal entries, with their lines",
        "description": "The booked entries posted or reversed since a moment, each with all its lines, oldest change first. A posted entry never changes; when it is reversed it comes again, marked `reversed`, and the entry that takes it back comes as a new one. `from`, `to` and `accountCode` narrow the read. A page ends early past 5,000 lines.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the journal entries posted or reversed at or after it are served, oldest change first. Left out: all of them.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most, 1 to 100. Left out: 50.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "A day, YYYY-MM-DD. Only the entries dated on or after it are served.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "A day, YYYY-MM-DD, on or after from. Only the entries dated on or before it are served.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "accountCode",
            "in": "query",
            "required": false,
            "description": "The code of an account of the chart. Only the entries with a line on it are served, each with all its lines.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[^\u0000]*$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of entries.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/JournalEntry"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_JOURNAL_ENTRY_ACCOUNT_UNKNOWN`: No account of the company's chart has this accountCode.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JOURNAL_ENTRY_ACCOUNT_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No account of the company's chart has this accountCode.",
                      "code": "EXT_JOURNAL_ENTRY_ACCOUNT_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/journal-entries"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Journal Entries",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_journal_entries"
      }
    },
    "/ext/trial-balance": {
      "get": {
        "operationId": "trial-balance.read",
        "tags": [
          "Accounting"
        ],
        "summary": "The trial balance between two days",
        "description": "Per account: what it held when the period starts, the period’s debits and credits, and what it holds on its last day, in the base currency. Computed by the service behind Mast’s own Trial Balance, so the figures are the ones the app shows for the same days.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "The period's first day, YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "The period's last day, YYYY-MM-DD, on or after from.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "closingPeriod",
            "in": "query",
            "required": false,
            "description": "true for the year-end closing view: only the entries booked in the closing period are its movements, and it ends on the closed position. false or left out: the operating view, which leaves out the closing period of the fiscal year it ends in.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The trial balance.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrialBalance"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: from: Required, to: Required",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "from",
                            "message": "Required"
                          },
                          {
                            "field": "to",
                            "message": "Required"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/trial-balance"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Financial Statement",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ_LIMITED",
          "calls": 60,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_get_trial_balance"
      }
    },
    "/ext/bank-accounts": {
      "get": {
        "operationId": "bank-accounts.list",
        "tags": [
          "Banking"
        ],
        "summary": "Bank accounts, with their balances",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the bank accounts changed at or after it are served, oldest change first. Left out: all of them.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most, 1 to 100. Left out: 50.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of bank accounts.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BankAccount"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`EXT_BANK_DATA_TWO_FACTOR_ACCOUNT`: This account requires two-step verification at sign-in, which an API key cannot give: its bank accounts and bank lines are not served to a key. Every other call of the API answers.\n\n`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_BANK_DATA_TWO_FACTOR_ACCOUNT": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This account requires two-step verification at sign-in, which an API key cannot give: its bank accounts and bank lines are not served to a key. Every other call of the API answers.",
                      "code": "EXT_BANK_DATA_TWO_FACTOR_ACCOUNT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  },
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-accounts"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Bank Accounts",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_bank_accounts"
      }
    },
    "/ext/bank-transactions": {
      "get": {
        "operationId": "bank-transactions.list",
        "tags": [
          "Banking"
        ],
        "summary": "Bank lines",
        "description": "The lines of the company’s bank accounts changed since a moment, oldest change first. `bankAccountId`, `from` and `to` narrow the read. A line changes when it is reconciled, excluded or parked, and comes again then.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the bank lines changed at or after it are served, oldest change first. Left out: all of them.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most, 1 to 100. Left out: 50.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "A day, YYYY-MM-DD. Only the lines booked on or after it are served.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "A day, YYYY-MM-DD, on or after from. Only the lines booked on or before it are served.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bankAccountId",
            "in": "query",
            "required": false,
            "description": "The id of a bank account of the company (GET /ext/bank-accounts). Only its lines are served.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[^\u0000]*$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of bank lines.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BankTransaction"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`EXT_BANK_DATA_TWO_FACTOR_ACCOUNT`: This account requires two-step verification at sign-in, which an API key cannot give: its bank accounts and bank lines are not served to a key. Every other call of the API answers.\n\n`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_BANK_DATA_TWO_FACTOR_ACCOUNT": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This account requires two-step verification at sign-in, which an API key cannot give: its bank accounts and bank lines are not served to a key. Every other call of the API answers.",
                      "code": "EXT_BANK_DATA_TWO_FACTOR_ACCOUNT",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  },
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_BANK_TRANSACTION_ACCOUNT_UNKNOWN`: No bank account of the company has this bankAccountId.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_BANK_TRANSACTION_ACCOUNT_UNKNOWN": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No bank account of the company has this bankAccountId.",
                      "code": "EXT_BANK_TRANSACTION_ACCOUNT_UNKNOWN",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bank-transactions"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Bank Statement",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_bank_transactions"
      }
    },
    "/ext/suppliers": {
      "get": {
        "operationId": "suppliers.list",
        "tags": [
          "Purchases"
        ],
        "summary": "Suppliers",
        "description": "The company’s suppliers changed since a moment, yours and the ones people made in Mast (`externalRef` null), oldest change first. A deleted supplier drops out of the list.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the suppliers changed at or after it are served, oldest change first. Left out: all of them.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most, 1 to 100. Left out: 50.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of suppliers.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Supplier"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Supplier",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_suppliers"
      },
      "post": {
        "operationId": "suppliers.create",
        "tags": [
          "Purchases"
        ],
        "summary": "Make a supplier",
        "description": "Makes a supplier under your own id. To make it or change it in one call whatever its state, use `PUT /ext/suppliers/{externalRef}`. Mast’s own rules on the VAT status refuse a number its country does not write, a registered supplier without one, and a number beside a status that takes none, each 400 under a code of its own (`SUPPLIER_CH_VAT_NUMBER_REQUIRED`, `SUPPLIER_CH_VAT_NUMBER_FORMAT`, `SUPPLIER_CH_VAT_NUMBER_FORBIDDEN`, and their like). No call writes the supplier’s bank account, its accounting defaults, its categories or its blacklist mark: a field naming one is dropped, and what the supplier held stays as it was.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalRef": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$",
                    "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "The supplier's name: what its bills, the payment runs and Mast's lists show. Two live suppliers of a company never share one."
                  },
                  "vatStatus": {
                    "type": "string",
                    "enum": [
                      "registered",
                      "foreign_registered",
                      "foreign_not_registered",
                      "not_registered"
                    ],
                    "description": "Its VAT standing in the VAT territory of the company's own country: `registered` (registered there, from inside it), `foreign_registered` (registered there, from abroad), `foreign_not_registered` (abroad, not registered there) or `not_registered` (inside it, not registered). The first two take `vatNumber` and require it, the last two refuse one. `unknown`, which a read answers for a supplier saved before Mast asked for the status, is never written."
                  },
                  "businessType": {
                    "description": "Its legal form: `corporation_company` (a company), `sole_proprietorship`, `nonprofit_association`, `government_public` (an administration) or `other`. Left out of a create, `corporation_company`.",
                    "type": "string",
                    "enum": [
                      "corporation_company",
                      "sole_proprietorship",
                      "nonprofit_association",
                      "government_public",
                      "other"
                    ]
                  },
                  "address": {
                    "description": "Where the supplier is. A part left out stays as it is.",
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 200,
                        "description": "Street and number, on one line. Null or an empty string removes it."
                      },
                      "postalCode": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 20,
                        "description": "Null or an empty string removes it."
                      },
                      "city": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 100,
                        "description": "Null or an empty string removes it."
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1,
                        "maxLength": 100,
                        "description": "The country's name, as the supplier's card in Mast writes it (\"France\", \"Germany\"). Left out of a create, or null there, the company's own country; left out of a change, or null, the one the supplier holds."
                      }
                    }
                  },
                  "registrationNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100,
                    "description": "Its number in the commercial register (a UID, or a foreign registry's id), as you record it. Null or an empty string removes it."
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 254,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
                    "description": "The address its correspondence goes to. Null removes it."
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "Its phone number in its international form, + and its country calling code first (`+41 44 000 00 00`). Mast keeps it without spaces (`+41440000000`) and serves it so. Null or an empty string removes it."
                  },
                  "vatNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 40,
                    "description": "Its VAT number in the VAT territory of the company's own country, in any spelling that country writes it in (`CHE-123.456.789 MWST`): Mast checks it as that country does, keeps it compact and serves it so (`CHE123456789`). With `registered` and `foreign_registered` only. Null or an empty string removes it."
                  },
                  "foreignTaxId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 40,
                    "description": "A supplier's own tax id in its country abroad (`DE123456789`). Null or an empty string removes it."
                  },
                  "foreignTaxIdCountry": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "pattern": "^[A-Za-z]{2}$",
                    "description": "The country that gave `foreignTaxId`, ISO 3166-1 alpha-2 (`DE`). Null removes it."
                  },
                  "currency": {
                    "description": "The ISO 4217 code its bills default to, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out of a create, the company's base currency.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "paymentTermsDays": {
                    "description": "Its net payment terms in whole days, 0 for due on receipt. 30 when a create leaves them out.",
                    "type": "number"
                  }
                },
                "required": [
                  "externalRef",
                  "name",
                  "vatStatus"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The supplier made.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Supplier"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_SUPPLIER_INVALID`: This supplier is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This supplier is not valid.",
                      "code": "EXT_SUPPLIER_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_SUPPLIER_EXISTS`: A supplier with this externalRef already exists in the company: update it with PATCH or PUT.\n\n`EXT_SUPPLIER_ARCHIVED`: The supplier with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`SUPPLIER_NAME_EXISTS`: If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one.\n\n`SUPPLIER_EMAIL_EXISTS`: Another supplier of the company has this e-mail address.\n\n`SUPPLIER_PHONE_EXISTS`: Another supplier of the company has this phone number.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_EXISTS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A supplier with this externalRef already exists in the company: update it with PATCH or PUT.",
                      "code": "EXT_SUPPLIER_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "EXT_SUPPLIER_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The supplier with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_SUPPLIER_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "SUPPLIER_NAME_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A supplier named \"Muster Bureau AG\" already exists. Give this one a different name, or edit the existing entry.",
                      "code": "SUPPLIER_NAME_EXISTS",
                      "details": {
                        "name": "Muster Bureau AG"
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "SUPPLIER_EMAIL_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "Another supplier of the company has this e-mail address.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "Supplier with email compta@muster-bureau.example already exists",
                      "code": "SUPPLIER_EMAIL_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "SUPPLIER_PHONE_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "Another supplier of the company has this phone number.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "Supplier with phone +41440000000 already exists",
                      "code": "SUPPLIER_PHONE_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: externalRef: Required, name: Required, vatStatus: Required",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "externalRef",
                            "message": "Required"
                          },
                          {
                            "field": "name",
                            "message": "Required"
                          },
                          {
                            "field": "vatStatus",
                            "message": "Required"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Supplier",
          "action": "create"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/suppliers/{externalRef}": {
      "get": {
        "operationId": "suppliers.read",
        "tags": [
          "Purchases"
        ],
        "summary": "A supplier, by your reference",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The supplier.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Supplier"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_SUPPLIER_NOT_FOUND`: No supplier of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No supplier of the company has this reference.",
                      "code": "EXT_SUPPLIER_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Supplier",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_get_supplier"
      },
      "put": {
        "operationId": "suppliers.upsert",
        "tags": [
          "Purchases"
        ],
        "summary": "Make or change a supplier",
        "description": "The call a sync makes: when the company has no supplier under this reference it is made, and the body must then hold what a creation needs (name, VAT status); else the fields given are changed and the others stay. Safe to repeat. Mast’s own rules on the VAT status refuse a number its country does not write, a registered supplier without one, and a number beside a status that takes none, each 400 under a code of its own (`SUPPLIER_CH_VAT_NUMBER_REQUIRED`, `SUPPLIER_CH_VAT_NUMBER_FORMAT`, `SUPPLIER_CH_VAT_NUMBER_FORBIDDEN`, and their like). No call writes the supplier’s bank account, its accounting defaults, its categories or its blacklist mark: a field naming one is dropped, and what the supplier held stays as it was.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "description": "The supplier's name: what its bills, the payment runs and Mast's lists show. Two live suppliers of a company never share one.",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "vatStatus": {
                    "description": "Its VAT standing in the VAT territory of the company's own country: `registered` (registered there, from inside it), `foreign_registered` (registered there, from abroad), `foreign_not_registered` (abroad, not registered there) or `not_registered` (inside it, not registered). The first two take `vatNumber` and require it, the last two refuse one. `unknown`, which a read answers for a supplier saved before Mast asked for the status, is never written.",
                    "type": "string",
                    "enum": [
                      "registered",
                      "foreign_registered",
                      "foreign_not_registered",
                      "not_registered"
                    ]
                  },
                  "businessType": {
                    "description": "Its legal form: `corporation_company` (a company), `sole_proprietorship`, `nonprofit_association`, `government_public` (an administration) or `other`. Left out of a create, `corporation_company`.",
                    "type": "string",
                    "enum": [
                      "corporation_company",
                      "sole_proprietorship",
                      "nonprofit_association",
                      "government_public",
                      "other"
                    ]
                  },
                  "address": {
                    "description": "Where the supplier is. A part left out stays as it is.",
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 200,
                        "description": "Street and number, on one line. Null or an empty string removes it."
                      },
                      "postalCode": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 20,
                        "description": "Null or an empty string removes it."
                      },
                      "city": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 100,
                        "description": "Null or an empty string removes it."
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1,
                        "maxLength": 100,
                        "description": "The country's name, as the supplier's card in Mast writes it (\"France\", \"Germany\"). Left out of a create, or null there, the company's own country; left out of a change, or null, the one the supplier holds."
                      }
                    }
                  },
                  "registrationNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100,
                    "description": "Its number in the commercial register (a UID, or a foreign registry's id), as you record it. Null or an empty string removes it."
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 254,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
                    "description": "The address its correspondence goes to. Null removes it."
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "Its phone number in its international form, + and its country calling code first (`+41 44 000 00 00`). Mast keeps it without spaces (`+41440000000`) and serves it so. Null or an empty string removes it."
                  },
                  "vatNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 40,
                    "description": "Its VAT number in the VAT territory of the company's own country, in any spelling that country writes it in (`CHE-123.456.789 MWST`): Mast checks it as that country does, keeps it compact and serves it so (`CHE123456789`). With `registered` and `foreign_registered` only. Null or an empty string removes it."
                  },
                  "foreignTaxId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 40,
                    "description": "A supplier's own tax id in its country abroad (`DE123456789`). Null or an empty string removes it."
                  },
                  "foreignTaxIdCountry": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "pattern": "^[A-Za-z]{2}$",
                    "description": "The country that gave `foreignTaxId`, ISO 3166-1 alpha-2 (`DE`). Null removes it."
                  },
                  "currency": {
                    "description": "The ISO 4217 code its bills default to, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out of a create, the company's base currency.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "paymentTermsDays": {
                    "description": "Its net payment terms in whole days, 0 for due on receipt. 30 when a create leaves them out.",
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The supplier, changed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Supplier"
                }
              }
            }
          },
          "201": {
            "description": "The reference was new: the supplier was made.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Supplier"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_SUPPLIER_INVALID`: This supplier is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This supplier is not valid.",
                      "code": "EXT_SUPPLIER_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_SUPPLIER_ARCHIVED`: The supplier with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`SUPPLIER_NAME_EXISTS`: If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one.\n\n`SUPPLIER_EMAIL_EXISTS`: Another supplier of the company has this e-mail address.\n\n`SUPPLIER_PHONE_EXISTS`: Another supplier of the company has this phone number.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The supplier with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_SUPPLIER_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "SUPPLIER_NAME_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A supplier named \"Muster Bureau AG\" already exists. Give this one a different name, or edit the existing entry.",
                      "code": "SUPPLIER_NAME_EXISTS",
                      "details": {
                        "name": "Muster Bureau AG"
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "SUPPLIER_EMAIL_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "Another supplier of the company has this e-mail address.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "Supplier with email compta@muster-bureau.example already exists",
                      "code": "SUPPLIER_EMAIL_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "SUPPLIER_PHONE_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "Another supplier of the company has this phone number.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "Supplier with phone +41440000000 already exists",
                      "code": "SUPPLIER_PHONE_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`EXT_SUPPLIER_INCOMPLETE`: No supplier has this externalRef yet, and making one takes its name and its VAT status.\n\n`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_INCOMPLETE": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "No supplier has this externalRef yet, and making one takes its name and its VAT status.",
                      "code": "EXT_SUPPLIER_INCOMPLETE",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: name: Expected string, received number",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "name",
                            "message": "Expected string, received number"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Supplier",
          "action": "edit"
        },
        "x-mast-also-right": {
          "feature": "Supplier",
          "action": "create"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_save_supplier"
      },
      "patch": {
        "operationId": "suppliers.update",
        "tags": [
          "Purchases"
        ],
        "summary": "Change a supplier",
        "description": "Changes the fields given; a field left out stays as it is. Mast’s own rules on the VAT status refuse a number its country does not write, a registered supplier without one, and a number beside a status that takes none, each 400 under a code of its own (`SUPPLIER_CH_VAT_NUMBER_REQUIRED`, `SUPPLIER_CH_VAT_NUMBER_FORMAT`, `SUPPLIER_CH_VAT_NUMBER_FORBIDDEN`, and their like). No call writes the supplier’s bank account, its accounting defaults, its categories or its blacklist mark: a field naming one is dropped, and what the supplier held stays as it was.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "description": "Your own id of the resource, as you gave it when you made it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "The id your own system gives the resource. Unique per company for each kind of resource. Mast stores it as you send it, less the spaces around it (`crm-1042 ` is `crm-1042`) and any NUL character, which Mast takes out of every text of a body (in a path, a NUL is refused)."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "description": "The supplier's name: what its bills, the payment runs and Mast's lists show. Two live suppliers of a company never share one.",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "vatStatus": {
                    "description": "Its VAT standing in the VAT territory of the company's own country: `registered` (registered there, from inside it), `foreign_registered` (registered there, from abroad), `foreign_not_registered` (abroad, not registered there) or `not_registered` (inside it, not registered). The first two take `vatNumber` and require it, the last two refuse one. `unknown`, which a read answers for a supplier saved before Mast asked for the status, is never written.",
                    "type": "string",
                    "enum": [
                      "registered",
                      "foreign_registered",
                      "foreign_not_registered",
                      "not_registered"
                    ]
                  },
                  "businessType": {
                    "description": "Its legal form: `corporation_company` (a company), `sole_proprietorship`, `nonprofit_association`, `government_public` (an administration) or `other`. Left out of a create, `corporation_company`.",
                    "type": "string",
                    "enum": [
                      "corporation_company",
                      "sole_proprietorship",
                      "nonprofit_association",
                      "government_public",
                      "other"
                    ]
                  },
                  "address": {
                    "description": "Where the supplier is. A part left out stays as it is.",
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 200,
                        "description": "Street and number, on one line. Null or an empty string removes it."
                      },
                      "postalCode": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 20,
                        "description": "Null or an empty string removes it."
                      },
                      "city": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 100,
                        "description": "Null or an empty string removes it."
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1,
                        "maxLength": 100,
                        "description": "The country's name, as the supplier's card in Mast writes it (\"France\", \"Germany\"). Left out of a create, or null there, the company's own country; left out of a change, or null, the one the supplier holds."
                      }
                    }
                  },
                  "registrationNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100,
                    "description": "Its number in the commercial register (a UID, or a foreign registry's id), as you record it. Null or an empty string removes it."
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 254,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
                    "description": "The address its correspondence goes to. Null removes it."
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 30,
                    "description": "Its phone number in its international form, + and its country calling code first (`+41 44 000 00 00`). Mast keeps it without spaces (`+41440000000`) and serves it so. Null or an empty string removes it."
                  },
                  "vatNumber": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 40,
                    "description": "Its VAT number in the VAT territory of the company's own country, in any spelling that country writes it in (`CHE-123.456.789 MWST`): Mast checks it as that country does, keeps it compact and serves it so (`CHE123456789`). With `registered` and `foreign_registered` only. Null or an empty string removes it."
                  },
                  "foreignTaxId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 40,
                    "description": "A supplier's own tax id in its country abroad (`DE123456789`). Null or an empty string removes it."
                  },
                  "foreignTaxIdCountry": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "pattern": "^[A-Za-z]{2}$",
                    "description": "The country that gave `foreignTaxId`, ISO 3166-1 alpha-2 (`DE`). Null removes it."
                  },
                  "currency": {
                    "description": "The ISO 4217 code its bills default to, one of the currencies Mast offers: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MAD, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR. Left out of a create, the company's base currency.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "paymentTermsDays": {
                    "description": "Its net payment terms in whole days, 0 for due on receipt. 30 when a create leaves them out.",
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The supplier, changed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Supplier"
                }
              }
            }
          },
          "400": {
            "description": "`EXT_SUPPLIER_INVALID`: This supplier is not valid. The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.\n\n`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_INVALID": {
                    "description": "The answer does not say which field Mast’s own rules refused: compare what you sent with the fields above.",
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This supplier is not valid.",
                      "code": "EXT_SUPPLIER_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_SUPPLIER_NOT_FOUND`: No supplier of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No supplier of the company has this reference.",
                      "code": "EXT_SUPPLIER_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`SUPPLIER_NAME_EXISTS`: If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one.\n\n`SUPPLIER_EMAIL_EXISTS`: Another supplier of the company has this e-mail address.\n\n`SUPPLIER_PHONE_EXISTS`: Another supplier of the company has this phone number.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "SUPPLIER_NAME_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "If that supplier was made in Mast, give it your reference with `PATCH /ext/suppliers/by-id/{id}` rather than making a second one.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A supplier named \"Muster Bureau AG\" already exists. Give this one a different name, or edit the existing entry.",
                      "code": "SUPPLIER_NAME_EXISTS",
                      "details": {
                        "name": "Muster Bureau AG"
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "SUPPLIER_EMAIL_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "Another supplier of the company has this e-mail address.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "Supplier with email compta@muster-bureau.example already exists",
                      "code": "SUPPLIER_EMAIL_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "SUPPLIER_PHONE_EXISTS": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "Another supplier of the company has this phone number.",
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "Supplier with phone +41440000000 already exists",
                      "code": "SUPPLIER_PHONE_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: name: Expected string, received number",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "name",
                            "message": "Expected string, received number"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/example-externalRef"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Supplier",
          "action": "edit"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/suppliers/by-id/{id}": {
      "get": {
        "operationId": "suppliers.readById",
        "tags": [
          "Purchases"
        ],
        "summary": "A supplier, by Mast’s id",
        "description": "For a supplier made in Mast, which has no `externalRef` until you give it one.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The supplier.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Supplier"
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_SUPPLIER_NOT_FOUND`: No supplier of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No supplier of the company has this reference.",
                      "code": "EXT_SUPPLIER_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: String must contain at least 1 character(s)",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "",
                            "message": "String must contain at least 1 character(s)"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/%20"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Supplier",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        }
      },
      "patch": {
        "operationId": "suppliers.updateById",
        "tags": [
          "Purchases"
        ],
        "summary": "Give a supplier your reference, by Mast’s id",
        "description": "For a supplier that is already in Mast with no `externalRef`, because a person made or imported it there. The call gives it your own id: `PUT /ext/suppliers/{externalRef}` then finds that supplier and changes it. It also changes the reference a supplier holds, and `null` takes it away. The reference it already holds changes nothing. No other field is changed here: once the supplier holds your reference, change it by that.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mast’s own id of the resource: the `id` every read returns.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\u0000]*$",
              "description": "Mast's own id of the resource: the `id` field every read returns. A resource made in Mast has no externalRef and is read by it."
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalRef": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[^\u0000]*$",
                    "description": "Your own id for this supplier: from then on it is addressed by it (`/ext/suppliers/{externalRef}`). Unique per company. Null takes away the one it holds."
                  }
                },
                "required": [
                  "externalRef"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The supplier, with the reference it now holds.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "idempotent-replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Supplier"
                }
              }
            }
          },
          "400": {
            "description": "`IDEMPOTENCY_KEY_INVALID`: Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "IDEMPOTENCY_KEY_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "Idempotency-Key must be 1 to 255 visible ASCII characters, sent once.",
                      "code": "IDEMPOTENCY_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`EXT_SUPPLIER_NOT_FOUND`: No supplier of the company has this reference.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_NOT_FOUND": {
                    "value": {
                      "statusCode": 404,
                      "error": "NotFoundException",
                      "message": "No supplier of the company has this reference.",
                      "code": "EXT_SUPPLIER_NOT_FOUND",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "`EXT_SUPPLIER_EXISTS`: A supplier with this externalRef already exists in the company: update it with PATCH or PUT.\n\n`EXT_SUPPLIER_ARCHIVED`: The supplier with this externalRef was archived in Mast: restore it there, or use another reference.\n\n`IDEMPOTENCY_REQUEST_IN_PROGRESS`: This request is still being processed. Wait a moment, then try again.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_SUPPLIER_EXISTS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "A supplier with this externalRef already exists in the company: update it with PATCH or PUT.",
                      "code": "EXT_SUPPLIER_EXISTS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "EXT_SUPPLIER_ARCHIVED": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "The supplier with this externalRef was archived in Mast: restore it there, or use another reference.",
                      "code": "EXT_SUPPLIER_ARCHIVED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "IDEMPOTENCY_REQUEST_IN_PROGRESS": {
                    "value": {
                      "statusCode": 409,
                      "error": "ConflictException",
                      "message": "This request is still being processed. Wait a moment, then try again.",
                      "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`EXT_JSON_BODY_REQUIRED`: The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json. Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_JSON_BODY_REQUIRED": {
                    "description": "Nothing was done, and the call can be made again. A charset may follow the type (`application/json; charset=utf-8`).",
                    "value": {
                      "statusCode": 415,
                      "error": "UnsupportedMediaTypeException",
                      "message": "The body was not sent as JSON: send it as JSON, with the header Content-Type: application/json.",
                      "code": "EXT_JSON_BODY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.\n\n`IDEMPOTENCY_KEY_REUSED`: This Idempotency-Key was already used for a different request.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: externalRef: Required",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "externalRef",
                            "message": "Required"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  },
                  "IDEMPOTENCY_KEY_REUSED": {
                    "value": {
                      "statusCode": 422,
                      "error": "UnprocessableEntityException",
                      "message": "This Idempotency-Key was already used for a different request.",
                      "code": "IDEMPOTENCY_KEY_REUSED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/suppliers/by-id/example-id"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Supplier",
          "action": "edit"
        },
        "x-mast-rate-limit": {
          "tier": "MUTATE",
          "calls": 60,
          "perSeconds": 60
        }
      }
    },
    "/ext/bills": {
      "get": {
        "operationId": "bills.list",
        "tags": [
          "Purchases"
        ],
        "summary": "Supplier bills, with their lines",
        "description": "The bills and suppliers’ credit notes the Bills page lists, changed since a moment, each with its lines: status, days, amounts, what is paid and what is owed. An expense claim is never served. `from` and `to` narrow the read by invoice date. A page ends early past 2,000 lines, never inside a bill: follow `nextCursor`.",
        "parameters": [
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "An instant, ISO 8601 with its offset (2026-11-19T06:00:00Z). Only the supplier bills and credit notes changed at or after it are served, oldest change first. Left out: all of them.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The nextCursor of the page before, to read the page after it. Left out: the first page. A value that is no cursor, or a cursor of another list, is refused.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many rows a page holds at most, 1 to 100. Left out: 50.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "A day, YYYY-MM-DD. Only the bills dated (their invoice date) on or after it are served.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "A day, YYYY-MM-DD, on or after from. Only the bills dated (their invoice date) on or before it are served.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of bills.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Bill"
                      },
                      "description": "The rows of this page, oldest change first."
                    },
                    "nextCursor": {
                      "description": "Pass it back as `cursor` to read the next page. Null when there is nothing more for now.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`EXT_CURSOR_INVALID`: This cursor is not one this list gave: start again without it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "EXT_CURSOR_INVALID": {
                    "value": {
                      "statusCode": 400,
                      "error": "BadRequestException",
                      "message": "This cursor is not one this list gave: start again without it.",
                      "code": "EXT_CURSOR_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: This route takes an API key (Authorization: Bearer mast_sk_…).\n\n`API_KEY_INVALID`: Invalid API key.\n\n`API_KEY_REVOKED`: This API key was revoked.\n\n`API_KEY_EXPIRED`: This API key has expired.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_REQUIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This route takes an API key (Authorization: Bearer mast_sk_…).",
                      "code": "API_KEY_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  },
                  "API_KEY_INVALID": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "Invalid API key.",
                      "code": "API_KEY_INVALID",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  },
                  "API_KEY_REVOKED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key was revoked.",
                      "code": "API_KEY_REVOKED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  },
                  "API_KEY_EXPIRED": {
                    "value": {
                      "statusCode": 401,
                      "error": "UnauthorizedException",
                      "message": "This API key has expired.",
                      "code": "API_KEY_EXPIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`API_KEY_COMPANY_MISMATCH`: This API key acts in another company than the one the request names. A key acts in its own company and needs no `x-company-id` header: leave it out.\n\n`PUBLIC_API_NOT_ENABLED`: The API is not open for this account.\n\n`ACCESS_DENIED_ROLE_REQUIRED`: Access denied: insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "API_KEY_COMPANY_MISMATCH": {
                    "description": "A key acts in its own company and needs no `x-company-id` header: leave it out.",
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "This API key acts in another company than the one the request names.",
                      "code": "API_KEY_COMPANY_MISMATCH",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  },
                  "PUBLIC_API_NOT_ENABLED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "The API is not open for this account.",
                      "code": "PUBLIC_API_NOT_ENABLED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  },
                  "ACCESS_DENIED_ROLE_REQUIRED": {
                    "value": {
                      "statusCode": 403,
                      "error": "ForbiddenException",
                      "message": "Access denied: insufficient permissions",
                      "code": "ACCESS_DENIED_ROLE_REQUIRED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION_FAILED`: The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "VALIDATION_FAILED": {
                    "summary": "One request’s answer: its words and details name what that request sent.",
                    "description": "The request is not shaped as this call expects: `details.fieldErrors` names each field and why, and the message says the same in one line.",
                    "value": {
                      "statusCode": 422,
                      "error": "Validation Error",
                      "message": "Validation failed: updatedSince: Invalid datetime",
                      "code": "VALIDATION_FAILED",
                      "details": {
                        "fieldErrors": [
                          {
                            "field": "updatedSince",
                            "message": "Invalid datetime"
                          }
                        ]
                      },
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills?updatedSince=yesterday"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMITED": {
                    "value": {
                      "statusCode": 429,
                      "error": "Too Many Requests",
                      "message": "Too many calls of this kind in a minute. Wait for the seconds Retry-After gives, then call again.",
                      "code": "RATE_LIMITED",
                      "timestamp": "2026-11-19T08:30:00.000Z",
                      "path": "/api/v1/ext/bills"
                    }
                  }
                }
              }
            }
          }
        },
        "x-mast-right": {
          "feature": "Supplier Bills",
          "action": "read"
        },
        "x-mast-rate-limit": {
          "tier": "READ",
          "calls": 300,
          "perSeconds": 60
        },
        "x-mast-mcp-tool": "mast_list_bills"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key of the company (`mast_sk_…`), made in Mast under Settings, API keys, sent as `Authorization: Bearer <key>`. It acts in one company, with the rights of the role it was given."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "A value of your own (1 to 255 visible ASCII characters), unique per act. A repeat of the same call with the same key within 24 hours is answered with what the first one was answered, and nothing is done twice.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "The id Mast logs the call under: quote it when you write to Mast about a call. Yours when you sent one (letters, digits and `.` `_` `:` `-`, up to 128 characters).",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "RateLimitLimit": {
        "description": "How many calls of this kind the key may make in a minute.",
        "required": true,
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitRemaining": {
        "description": "How many of them are left in this minute.",
        "required": true,
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitReset": {
        "description": "The seconds until the minute ends.",
        "required": true,
        "schema": {
          "type": "integer"
        }
      },
      "RetryAfter": {
        "description": "The seconds to wait before calling again.",
        "required": true,
        "schema": {
          "type": "integer"
        }
      },
      "IdempotentReplayed": {
        "description": "`true` when the answer is the one the first call with this `Idempotency-Key` was given, and nothing was done again. Absent otherwise.",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "true"
          ]
        }
      }
    },
    "schemas": {
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "Unique in the chart: the key journal lines and the trial balance name an account by."
          },
          "name": {
            "type": "string",
            "description": "In the company’s accounting language (`GET /ext/company`)."
          },
          "type": {
            "type": "string",
            "enum": [
              "asset",
              "liability",
              "equity",
              "revenue",
              "expense"
            ]
          },
          "category": {
            "type": "string",
            "description": "The chart’s category (`current_assets`, `operating_expenses`, …)."
          },
          "isGroup": {
            "type": "boolean",
            "description": "A heading that sums the accounts under it; it takes no line."
          },
          "parentCode": {
            "description": "The code of the heading it sits under.",
            "type": [
              "string",
              "null"
            ]
          },
          "isActive": {
            "type": "boolean"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217: the currency the account is kept in. Its ledger figures stay in the base currency."
          },
          "isBankOrCash": {
            "type": "boolean",
            "description": "A bank or cash account."
          },
          "subledger": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "customer",
              "supplier",
              "employee",
              null
            ],
            "description": "Whose balances the account is kept by: a receivables account tracks customers, a payables account suppliers. Null for none."
          },
          "systemRoles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The roles Mast books by that are mapped to this account (`vat_output_standard`, `current_year_result`, …), as of the read."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "code",
          "name",
          "type",
          "category",
          "isGroup",
          "parentCode",
          "isActive",
          "currency",
          "isBankOrCash",
          "subledger",
          "systemRoles",
          "createdAt",
          "updatedAt"
        ],
        "description": "An account of the chart, or one of its headings (`isGroup`)."
      },
      "BankAccount": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "bankName": {
            "type": "string"
          },
          "accountHolder": {
            "type": [
              "string",
              "null"
            ]
          },
          "iban": {
            "type": [
              "string",
              "null"
            ]
          },
          "bic": {
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217: the currency the account is held in."
          },
          "type": {
            "description": "`bank_account`, `credit_card`, … as the company filed it.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "suspended",
              "closed"
            ]
          },
          "ledgerAccountCode": {
            "description": "The ledger account its lines are booked on (`GET /ext/accounts`).",
            "type": [
              "string",
              "null"
            ]
          },
          "statementBalance": {
            "description": "The closing balance of the latest statement Mast holds, in `currency`.",
            "type": [
              "number",
              "null"
            ]
          },
          "statementBalanceDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The day of that statement balance."
          },
          "computedBalance": {
            "description": "The opening balance plus every movement Mast holds, in `currency`, as of the read: it also counts lines booked after the latest statement.",
            "type": [
              "number",
              "null"
            ]
          },
          "latestTransactionDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The booking day of the account’s latest line."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "bankName",
          "accountHolder",
          "iban",
          "bic",
          "currency",
          "type",
          "status",
          "ledgerAccountCode",
          "statementBalance",
          "statementBalanceDate",
          "computedBalance",
          "latestTransactionDate",
          "createdAt",
          "updatedAt"
        ],
        "description": "A bank account of the company."
      },
      "BankTransaction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "bankAccountId": {
            "type": "string"
          },
          "bookingDate": {
            "type": "string",
            "format": "date"
          },
          "valueDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "amount": {
            "type": "number",
            "description": "Always positive; `direction` says which way the money went."
          },
          "direction": {
            "type": "string",
            "enum": [
              "in",
              "out"
            ]
          },
          "currency": {
            "type": "string"
          },
          "amountInBaseCurrency": {
            "description": "`amount` in the company’s base currency; null when no rate could convert it.",
            "type": [
              "number",
              "null"
            ]
          },
          "counterpartyName": {
            "type": [
              "string",
              "null"
            ]
          },
          "counterpartyAccount": {
            "type": [
              "string",
              "null"
            ]
          },
          "reference": {
            "description": "The reference a person reads on the line in Mast.",
            "type": [
              "string",
              "null"
            ]
          },
          "text": {
            "description": "The line’s own text, as the bank wrote it.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "booked",
              "pending",
              "cancelled"
            ],
            "description": "The bank’s state of the movement."
          },
          "reconciliation": {
            "type": "string",
            "enum": [
              "unreconciled",
              "reconciled",
              "partially_matched",
              "excluded",
              "parked"
            ],
            "description": "Where the line stands in the books."
          },
          "exclusion": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "duplicate",
              "no_booking_needed",
              "import",
              null
            ],
            "description": "How an excluded line was set aside: a person’s « Duplicate » or « No booking needed », or by an import."
          },
          "countsAsMovement": {
            "type": "boolean",
            "description": "False for a duplicate of another line: no balance of Mast counts it."
          },
          "journalEntryId": {
            "description": "The journal entry that books the line (`GET /ext/journal-entries`).",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "bankAccountId",
          "bookingDate",
          "valueDate",
          "amount",
          "direction",
          "currency",
          "amountInBaseCurrency",
          "counterpartyName",
          "counterpartyAccount",
          "reference",
          "text",
          "status",
          "reconciliation",
          "exclusion",
          "countsAsMovement",
          "journalEntryId",
          "createdAt",
          "updatedAt"
        ],
        "description": "A line of a bank account."
      },
      "Bill": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "bill",
              "credit_note"
            ]
          },
          "number": {
            "type": "string",
            "description": "Mast’s own number for the document."
          },
          "supplierInvoiceNumber": {
            "description": "The number the supplier gave it.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "description": "`inbox`, `draft`, `pending_approval`, `disputed`, `approved`, `submitted`, `posted`, `in_payment`, `payment_processed`, `partially_paid`, `paid`, `overdue`, `cancelled`, `reversed`."
          },
          "supplierId": {
            "description": "The `id` of `GET /ext/suppliers`; null for a bill not filed under a supplier yet.",
            "type": [
              "string",
              "null"
            ]
          },
          "invoiceDate": {
            "type": "string",
            "format": "date"
          },
          "bookingDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The day it is booked on, when that is not its own date."
          },
          "dueDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "currency": {
            "type": "string"
          },
          "exchangeRate": {
            "description": "Base currency per unit of `currency`, as stored: indicative until the bill is booked, the booked rate after. Null in the base currency, and for a foreign bill no rate was found for.",
            "type": [
              "number",
              "null"
            ]
          },
          "netAmount": {
            "type": "number",
            "description": "In `currency`."
          },
          "vatAmount": {
            "type": "number"
          },
          "total": {
            "type": "number"
          },
          "amountPaid": {
            "type": "number"
          },
          "amountDue": {
            "type": "number"
          },
          "netAmountInBaseCurrency": {
            "description": "`netAmount` in the company’s base currency, at `exchangeRate`; null for a foreign bill with no rate, never converted at 1 to 1.",
            "type": [
              "number",
              "null"
            ]
          },
          "totalInBaseCurrency": {
            "type": [
              "number",
              "null"
            ]
          },
          "isReverseCharge": {
            "type": "boolean",
            "description": "The company assesses the VAT on itself: it owes the supplier the net amount."
          },
          "isOpeningItem": {
            "type": "boolean",
            "description": "An open payable a migration brought over: its amounts are what was still owed then, and the opening balance carries it."
          },
          "journalEntryId": {
            "description": "The journal entry that books it (`GET /ext/journal-entries`).",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillLine"
            }
          }
        },
        "required": [
          "id",
          "type",
          "number",
          "supplierInvoiceNumber",
          "status",
          "supplierId",
          "invoiceDate",
          "bookingDate",
          "dueDate",
          "currency",
          "exchangeRate",
          "netAmount",
          "vatAmount",
          "total",
          "amountPaid",
          "amountDue",
          "netAmountInBaseCurrency",
          "totalInBaseCurrency",
          "isReverseCharge",
          "isOpeningItem",
          "journalEntryId",
          "createdAt",
          "updatedAt",
          "lines"
        ],
        "description": "A supplier’s bill, or a supplier’s credit note, with its lines."
      },
      "BillLine": {
        "type": "object",
        "properties": {
          "lineNumber": {
            "type": "integer",
            "description": "Its rank on the bill, from 1."
          },
          "description": {
            "type": "string"
          },
          "quantity": {
            "type": "number"
          },
          "unit": {
            "type": "string"
          },
          "unitPrice": {
            "type": "number"
          },
          "discountPercent": {
            "type": [
              "number",
              "null"
            ]
          },
          "netAmount": {
            "type": "number",
            "description": "The line after its discount, without VAT, in the bill’s currency."
          },
          "vatCode": {
            "description": "The VAT rate code of the line.",
            "type": [
              "string",
              "null"
            ]
          },
          "vatRatePercent": {
            "type": "number"
          },
          "vatAmount": {
            "type": "number"
          },
          "total": {
            "type": "number",
            "description": "The line with its VAT, in the bill’s currency."
          },
          "expenseAccountCode": {
            "description": "The account the line is booked on (`GET /ext/accounts`).",
            "type": [
              "string",
              "null"
            ]
          },
          "costCenterCode": {
            "description": "The line’s one cost centre; null with none, and with several.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "lineNumber",
          "description",
          "quantity",
          "unit",
          "unitPrice",
          "discountPercent",
          "netAmount",
          "vatCode",
          "vatRatePercent",
          "vatAmount",
          "total",
          "expenseAccountCode",
          "costCenterCode"
        ],
        "description": "A line of a supplier’s bill."
      },
      "Company": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "The legal name."
          },
          "tradingName": {
            "type": [
              "string",
              "null"
            ]
          },
          "countryCode": {
            "description": "ISO 3166-1 alpha-2: the country whose rules the books follow.",
            "type": [
              "string",
              "null"
            ]
          },
          "baseCurrency": {
            "type": "string",
            "description": "ISO 4217: the currency the ledger is kept in. Every ledger figure of the API is in it."
          },
          "accountingLanguage": {
            "type": "string",
            "description": "The language account and journal names are written in (`en`, `fr`, `de`, `it`)."
          },
          "timeZone": {
            "type": "string",
            "description": "The IANA zone the accounting day is read in."
          },
          "today": {
            "type": "string",
            "format": "date",
            "description": "Today’s accounting day, in `timeZone`."
          },
          "vat": {
            "type": "object",
            "properties": {
              "registered": {
                "type": "boolean",
                "description": "Whether the company is liable for VAT on `today`."
              },
              "number": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "registeredFrom": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date",
                "description": "The first liable day, when the company recorded one."
              },
              "deregisteredFrom": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date",
                "description": "The first day no longer liable, when the company de-registered."
              }
            },
            "required": [
              "registered",
              "number",
              "registeredFrom",
              "deregisteredFrom"
            ]
          },
          "fiscalYears": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FiscalYear"
            },
            "description": "Oldest first."
          }
        },
        "required": [
          "id",
          "name",
          "tradingName",
          "countryCode",
          "baseCurrency",
          "accountingLanguage",
          "timeZone",
          "today",
          "vat",
          "fiscalYears"
        ],
        "description": "The company a key acts in: what a reader needs to read its books right."
      },
      "CostCenterShare": {
        "type": "object",
        "properties": {
          "costCenterCode": {
            "type": "string",
            "description": "The cost centre’s code, as the company named it."
          },
          "costCenterClass": {
            "type": "string",
            "description": "The class the share is filed under (`Department`, …), as it was when the line was booked."
          },
          "percentage": {
            "type": "number",
            "description": "Of the line, in percent, as it was entered: the shares of one class add up to 100, to their rounding."
          },
          "amount": {
            "type": "number",
            "description": "Of the line’s amount, in the base currency, always positive: the shares of one class add up to the line exactly."
          }
        },
        "required": [
          "costCenterCode",
          "costCenterClass",
          "percentage",
          "amount"
        ],
        "description": "One cost centre’s share of a journal line, within one class of cost centres."
      },
      "CreditNote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "externalRef": {
            "description": "Your own id of the document. Null for one made in Mast.",
            "type": [
              "string",
              "null"
            ]
          },
          "documentNumber": {
            "type": "string",
            "description": "`Draft-…` until issued, then the official number."
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "open",
              "paid",
              "cancelled"
            ],
            "description": "`open` while it still holds credit, `paid` once all of it was applied or refunded."
          },
          "customerId": {
            "type": "string",
            "description": "The customer’s id in Mast, the `id` of `GET /ext/customers`."
          },
          "customerExternalRef": {
            "type": [
              "string",
              "null"
            ]
          },
          "customerNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "customerName": {
            "type": [
              "string",
              "null"
            ]
          },
          "issueDate": {
            "type": "string",
            "format": "date"
          },
          "supplyPeriodStart": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The time of supply, when it is not the issue date."
          },
          "supplyPeriodEnd": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "language": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "de",
              "fr",
              "it",
              "en",
              null
            ]
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "introText": {
            "description": "Printed above the lines.",
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "footerText": {
            "description": "Printed at the foot of the document.",
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "priceIncludesVat": {
            "type": "boolean",
            "description": "Whether the lines’ unit prices include VAT."
          },
          "subtotal": {
            "type": "number",
            "description": "The lines after their own discounts: net, or with VAT when the prices include it."
          },
          "discountPercent": {
            "description": "The discount on the whole document, when it is a percentage.",
            "type": [
              "number",
              "null"
            ]
          },
          "discountAmount": {
            "type": "number",
            "description": "The discount on the whole document, as an amount; 0 for none."
          },
          "netAmount": {
            "type": "number",
            "description": "What the document bills, net of VAT, as its PDF prints it."
          },
          "vatAmount": {
            "type": "number"
          },
          "total": {
            "type": "number"
          },
          "amountPaid": {
            "type": "number"
          },
          "amountDue": {
            "type": "number",
            "description": "What is still owed."
          },
          "vatRows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VatRow"
            },
            "description": "The VAT per rate, adding up to `vatAmount`."
          },
          "invoicedNetAmount": {
            "description": "What the document counts for in a sum of what was invoiced, net of VAT: add it over the invoices and the credit notes of a period. Null on a draft, on a cancelled document and on a credit note of a cancelled invoice.",
            "type": [
              "number",
              "null"
            ]
          },
          "baseCurrency": {
            "type": "string",
            "description": "The currency the company’s books are kept in."
          },
          "exchangeRate": {
            "description": "The rate stored on the document, 1 in the base currency; null on a foreign document Mast holds no rate for.",
            "type": [
              "number",
              "null"
            ]
          },
          "baseNetAmount": {
            "description": "`netAmount` in the base currency at that rate; null where there is no rate, never converted at 1:1.",
            "type": [
              "number",
              "null"
            ]
          },
          "baseVatAmount": {
            "type": [
              "number",
              "null"
            ]
          },
          "baseTotal": {
            "type": [
              "number",
              "null"
            ]
          },
          "baseAmountDue": {
            "type": [
              "number",
              "null"
            ]
          },
          "baseInvoicedNetAmount": {
            "type": [
              "number",
              "null"
            ]
          },
          "lines": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/DocumentLine"
            },
            "description": "The document’s lines. Always there on a single read; on a list only with `include=lines`, null otherwise."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "invoiceId": {
            "description": "The invoice it credits, when Mast knows it.",
            "type": [
              "string",
              "null"
            ]
          },
          "invoiceExternalRef": {
            "type": [
              "string",
              "null"
            ]
          },
          "invoiceNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "creditsCancelledInvoice": {
            "type": "boolean",
            "description": "True when the invoice it credits is itself cancelled: the two are out of a sum of what was invoiced together."
          }
        },
        "required": [
          "id",
          "externalRef",
          "documentNumber",
          "status",
          "customerId",
          "customerExternalRef",
          "customerNumber",
          "customerName",
          "issueDate",
          "supplyPeriodStart",
          "supplyPeriodEnd",
          "language",
          "reference",
          "title",
          "introText",
          "notes",
          "footerText",
          "currency",
          "priceIncludesVat",
          "subtotal",
          "discountPercent",
          "discountAmount",
          "netAmount",
          "vatAmount",
          "total",
          "amountPaid",
          "amountDue",
          "vatRows",
          "invoicedNetAmount",
          "baseCurrency",
          "exchangeRate",
          "baseNetAmount",
          "baseVatAmount",
          "baseTotal",
          "baseAmountDue",
          "baseInvoicedNetAmount",
          "lines",
          "createdAt",
          "updatedAt",
          "invoiceId",
          "invoiceExternalRef",
          "invoiceNumber",
          "creditsCancelledInvoice"
        ],
        "description": "A credit note. Its amounts are below zero, so the invoices and the credit notes of a period add up to what was invoiced: `total` is what it credits, `amountPaid` what of it was applied to invoices or refunded, `amountDue` the credit it still holds."
      },
      "Customer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "externalRef": {
            "description": "Your own id of the customer. Null for a customer made in Mast.",
            "type": [
              "string",
              "null"
            ]
          },
          "number": {
            "type": "string",
            "description": "Mast’s own customer number."
          },
          "type": {
            "type": "string",
            "enum": [
              "business",
              "individual"
            ]
          },
          "name": {
            "type": "string",
            "description": "The name its documents carry: the company’s, or the person’s."
          },
          "companyName": {
            "type": [
              "string",
              "null"
            ]
          },
          "firstName": {
            "type": [
              "string",
              "null"
            ]
          },
          "lastName": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "description": "The address an invoice is sent to.",
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": "object",
            "properties": {
              "street": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postalCode": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "description": "The country’s name as Mast writes it.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "countryCode": {
                "description": "ISO 3166-1 alpha-2; null when Mast cannot read the country’s name.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "street",
              "postalCode",
              "city",
              "country",
              "countryCode"
            ],
            "description": "The billing address."
          },
          "language": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "de",
              "fr",
              "it",
              "en",
              null
            ],
            "description": "The language its documents are written in. Null when Mast holds a language the API has no word for."
          },
          "vatNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "registrationNumber": {
            "description": "Its commercial-register number (a UID, or a foreign registry’s id).",
            "type": [
              "string",
              "null"
            ]
          },
          "defaultDiscountPercent": {
            "type": "number",
            "description": "The discount Mast holds for this customer, in percent; 0 for none. An invoice takes it only when it asks (`applyCustomerDefaultDiscount`)."
          },
          "paymentTermsDays": {
            "type": "integer",
            "description": "Its net payment terms in days; 0 for due on receipt."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "externalRef",
          "number",
          "type",
          "name",
          "companyName",
          "firstName",
          "lastName",
          "email",
          "phone",
          "address",
          "language",
          "vatNumber",
          "registrationNumber",
          "defaultDiscountPercent",
          "paymentTermsDays",
          "createdAt",
          "updatedAt"
        ],
        "description": "A customer of the company."
      },
      "DocumentLine": {
        "type": "object",
        "properties": {
          "position": {
            "type": "integer",
            "description": "Its place on the document, from 1."
          },
          "sectionTitle": {
            "description": "The title of the section it sits in, when the document has sections.",
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": "string",
            "description": "The line’s words as the document prints them."
          },
          "productId": {
            "type": [
              "string",
              "null"
            ]
          },
          "productExternalRef": {
            "type": [
              "string",
              "null"
            ]
          },
          "productCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "quantity": {
            "type": "number"
          },
          "unit": {
            "type": "string"
          },
          "unitPrice": {
            "type": "number"
          },
          "discountPercent": {
            "description": "The line’s own discount, in percent.",
            "type": [
              "number",
              "null"
            ]
          },
          "discountAmount": {
            "type": "number",
            "description": "That discount as an amount."
          },
          "vatRatePercent": {
            "type": "number"
          },
          "vatRateCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "netAmount": {
            "type": "number",
            "description": "After the line’s own discount, before the document’s."
          },
          "vatAmount": {
            "type": "number",
            "description": "The VAT on that amount, before the document’s discount: the document’s own VAT, per rate, is in its `vatRows`."
          },
          "total": {
            "type": "number",
            "description": "`netAmount` and `vatAmount` together."
          },
          "invoicedNetAmount": {
            "description": "What the line counts for in a sum of lines, net of VAT: its share of what its document was issued for, so the lines of a document with a discount, or of a contract billed in stages, add up to what was invoiced. Null on a draft and on a cancelled document.",
            "type": [
              "number",
              "null"
            ]
          },
          "invoicedQuantity": {
            "description": "Its quantity at the same share.",
            "type": [
              "number",
              "null"
            ]
          },
          "revenueAccountCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "costCenterCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "comment": {
            "description": "A note printed under the line.",
            "type": [
              "string",
              "null"
            ]
          },
          "supplyPeriodStart": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "When this line was supplied, if not when the document says."
          },
          "supplyPeriodEnd": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          }
        },
        "required": [
          "position",
          "sectionTitle",
          "description",
          "productId",
          "productExternalRef",
          "productCode",
          "quantity",
          "unit",
          "unitPrice",
          "discountPercent",
          "discountAmount",
          "vatRatePercent",
          "vatRateCode",
          "netAmount",
          "vatAmount",
          "total",
          "invoicedNetAmount",
          "invoicedQuantity",
          "revenueAccountCode",
          "costCenterCode",
          "comment",
          "supplyPeriodStart",
          "supplyPeriodEnd"
        ],
        "description": "A line of an invoice or a credit note, as Mast holds it."
      },
      "Error": {
        "type": "object",
        "description": "What every refusal of the application answers. Branch on `code`, never on `message`. A refusal of Mast’s firewall, in front of the application, has another body: `statusCode` and `source`, a `code` on a 403 (the guide’s « Mast’s firewall »).",
        "properties": {
          "statusCode": {
            "type": "integer",
            "description": "The HTTP status, repeated."
          },
          "error": {
            "type": "string",
            "description": "The kind of refusal, e.g. `ConflictException`."
          },
          "message": {
            "type": "string",
            "description": "The refusal in English, for a developer. It may be reworded."
          },
          "code": {
            "type": "string",
            "description": "A stable word for the refusal, e.g. `EXT_INVOICE_EXISTS`. Absent only from an answer given before any route runs: the 400 of a body that is not valid JSON, the 404 of a path the API does not have."
          },
          "details": {
            "description": "What exactly was wrong, when the refusal says more: the fields a validation refused (`fieldErrors`)."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When Mast answered."
          },
          "path": {
            "type": "string",
            "description": "The path called, with its query string."
          }
        },
        "required": [
          "statusCode",
          "error",
          "message",
          "timestamp",
          "path"
        ]
      },
      "FiscalYear": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "As the company named it (« 2026 »)."
          },
          "startDate": {
            "type": "string",
            "format": "date",
            "description": "Its first day."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Its last day."
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "closed",
              "archived"
            ],
            "description": "`closed` and `archived` take no new entry."
          }
        },
        "required": [
          "id",
          "name",
          "startDate",
          "endDate",
          "status"
        ],
        "description": "A fiscal year of the company."
      },
      "Invoice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "externalRef": {
            "description": "Your own id of the document. Null for one made in Mast.",
            "type": [
              "string",
              "null"
            ]
          },
          "documentNumber": {
            "type": "string",
            "description": "`Draft-…` until issued, then the official number."
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "open",
              "overdue",
              "partially_paid",
              "paid",
              "cancelled",
              "paid_in_provider",
              "refunded_in_provider",
              "paid_outside_provider"
            ],
            "description": "`draft`: not issued, no official number. `open`: issued, nothing received, not due yet. `overdue`: issued, nothing received, due before today (judged on the day of the read). `partially_paid`, `paid`, `cancelled`. The three `…_provider` words are invoices a payment provider issued and collected."
          },
          "customerId": {
            "type": "string",
            "description": "The customer’s id in Mast, the `id` of `GET /ext/customers`."
          },
          "customerExternalRef": {
            "type": [
              "string",
              "null"
            ]
          },
          "customerNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "customerName": {
            "type": [
              "string",
              "null"
            ]
          },
          "issueDate": {
            "type": "string",
            "format": "date"
          },
          "supplyPeriodStart": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The time of supply, when it is not the issue date."
          },
          "supplyPeriodEnd": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "language": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "de",
              "fr",
              "it",
              "en",
              null
            ]
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "introText": {
            "description": "Printed above the lines.",
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "footerText": {
            "description": "Printed at the foot of the document.",
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "priceIncludesVat": {
            "type": "boolean",
            "description": "Whether the lines’ unit prices include VAT."
          },
          "subtotal": {
            "type": "number",
            "description": "The lines after their own discounts: net, or with VAT when the prices include it."
          },
          "discountPercent": {
            "description": "The discount on the whole document, when it is a percentage.",
            "type": [
              "number",
              "null"
            ]
          },
          "discountAmount": {
            "type": "number",
            "description": "The discount on the whole document, as an amount; 0 for none."
          },
          "netAmount": {
            "type": "number",
            "description": "What the document bills, net of VAT, as its PDF prints it."
          },
          "vatAmount": {
            "type": "number"
          },
          "total": {
            "type": "number"
          },
          "amountPaid": {
            "type": "number"
          },
          "amountDue": {
            "type": "number",
            "description": "What is still owed."
          },
          "vatRows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VatRow"
            },
            "description": "The VAT per rate, adding up to `vatAmount`."
          },
          "invoicedNetAmount": {
            "description": "What the document counts for in a sum of what was invoiced, net of VAT: add it over the invoices and the credit notes of a period. Null on a draft, on a cancelled document and on a credit note of a cancelled invoice.",
            "type": [
              "number",
              "null"
            ]
          },
          "baseCurrency": {
            "type": "string",
            "description": "The currency the company’s books are kept in."
          },
          "exchangeRate": {
            "description": "The rate stored on the document, 1 in the base currency; null on a foreign document Mast holds no rate for.",
            "type": [
              "number",
              "null"
            ]
          },
          "baseNetAmount": {
            "description": "`netAmount` in the base currency at that rate; null where there is no rate, never converted at 1:1.",
            "type": [
              "number",
              "null"
            ]
          },
          "baseVatAmount": {
            "type": [
              "number",
              "null"
            ]
          },
          "baseTotal": {
            "type": [
              "number",
              "null"
            ]
          },
          "baseAmountDue": {
            "type": [
              "number",
              "null"
            ]
          },
          "baseInvoicedNetAmount": {
            "type": [
              "number",
              "null"
            ]
          },
          "lines": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/DocumentLine"
            },
            "description": "The document’s lines. Always there on a single read; on a list only with `include=lines`, null otherwise."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "stage": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "down_payment",
              "progress",
              "final",
              null
            ],
            "description": "The invoice of a contract billed in stages; null on any other invoice."
          },
          "contractNetAmount": {
            "description": "The contract a staged invoice bills a part of; null on any other invoice.",
            "type": [
              "number",
              "null"
            ]
          },
          "contractTotal": {
            "type": [
              "number",
              "null"
            ]
          },
          "dueDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "paymentTermsDays": {
            "type": "integer"
          },
          "paymentTermsText": {
            "description": "The payment terms in words, printed on the invoice.",
            "type": [
              "string",
              "null"
            ]
          },
          "deliveryState": {
            "type": "string",
            "enum": [
              "not_sent",
              "sent_by_email",
              "sent_by_other_channel",
              "bounced",
              "failed"
            ]
          },
          "sentAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When it last went to the customer, where Mast recorded it."
          },
          "sentTo": {
            "type": [
              "string",
              "null"
            ]
          },
          "paidOn": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The day its last payment came, once it is paid; null when no payment tells."
          }
        },
        "required": [
          "id",
          "externalRef",
          "documentNumber",
          "status",
          "customerId",
          "customerExternalRef",
          "customerNumber",
          "customerName",
          "issueDate",
          "supplyPeriodStart",
          "supplyPeriodEnd",
          "language",
          "reference",
          "title",
          "introText",
          "notes",
          "footerText",
          "currency",
          "priceIncludesVat",
          "subtotal",
          "discountPercent",
          "discountAmount",
          "netAmount",
          "vatAmount",
          "total",
          "amountPaid",
          "amountDue",
          "vatRows",
          "invoicedNetAmount",
          "baseCurrency",
          "exchangeRate",
          "baseNetAmount",
          "baseVatAmount",
          "baseTotal",
          "baseAmountDue",
          "baseInvoicedNetAmount",
          "lines",
          "createdAt",
          "updatedAt",
          "stage",
          "contractNetAmount",
          "contractTotal",
          "dueDate",
          "paymentTermsDays",
          "paymentTermsText",
          "deliveryState",
          "sentAt",
          "sentTo",
          "paidOn"
        ],
        "description": "A customer invoice."
      },
      "InvoiceSendResult": {
        "type": "object",
        "properties": {
          "invoice": {
            "$ref": "#/components/schemas/Invoice"
          },
          "recipient": {
            "type": "string"
          },
          "deduplicated": {
            "type": "boolean",
            "description": "True when the same message was sent moments ago: no second e-mail went."
          }
        },
        "required": [
          "invoice",
          "recipient",
          "deduplicated"
        ],
        "description": "What sending an invoice answers."
      },
      "JournalEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "number": {
            "type": "string",
            "description": "The entry’s number in its company (`JE-2026-00042`)."
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "The day it is booked on."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "posted",
              "reversed"
            ],
            "description": "`reversed`: another entry takes it back (`reversedBy`); both stay in the books."
          },
          "entryType": {
            "type": "string",
            "description": "`normal`, `opening_balance`, `ytd_carryforward`, `closing_pnl`, `correction`, `vat_settlement`, …"
          },
          "isClosingPeriod": {
            "type": "boolean",
            "description": "Booked in the year-end closing period, apart from the year’s last month."
          },
          "isCarryForward": {
            "type": "boolean",
            "description": "A year-end carry-forward of an earlier version of Mast, or the entry reversing one: it restates balances the books already hold. No balance of Mast counts it; leave it out of a sum of lines too."
          },
          "journal": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JournalEntryFiling"
              },
              {
                "type": "null"
              }
            ]
          },
          "documentType": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JournalEntryFiling"
              },
              {
                "type": "null"
              }
            ]
          },
          "source": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "`invoice`, `credit_note`, `bill`, `expense`, `bank_reconciliation`, `bank_tx_gl`, `manual`, …"
              },
              "documentId": {
                "description": "The sales or purchase document it books, by its id in Mast.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "documentNumber": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "bankTransactionId": {
                "description": "The bank line it books: the `id` of `GET /ext/bank-transactions`.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "type",
              "documentId",
              "documentNumber",
              "bankTransactionId"
            ],
            "description": "What the entry books. Null for an entry a person wrote by hand."
          },
          "reverses": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JournalEntryRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "The entry this one takes back."
          },
          "reversedBy": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JournalEntryRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "The entry that takes this one back."
          },
          "currency": {
            "description": "The currency of the document or bank line the entry books, when its lane records one. The lines’ debits and credits stay in the base currency.",
            "type": [
              "string",
              "null"
            ]
          },
          "exchangeRate": {
            "description": "The rate that foreign money was booked at: base currency per unit of `currency`.",
            "type": [
              "number",
              "null"
            ]
          },
          "totalDebit": {
            "type": "number",
            "description": "In the base currency. Equal to `totalCredit`."
          },
          "totalCredit": {
            "type": "number"
          },
          "postedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Moves when the entry is posted, and once more if it is reversed."
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JournalEntryLine"
            }
          }
        },
        "required": [
          "id",
          "number",
          "date",
          "description",
          "reference",
          "status",
          "entryType",
          "isClosingPeriod",
          "isCarryForward",
          "journal",
          "documentType",
          "source",
          "reverses",
          "reversedBy",
          "currency",
          "exchangeRate",
          "totalDebit",
          "totalCredit",
          "postedAt",
          "createdAt",
          "updatedAt",
          "lines"
        ],
        "description": "A booked journal entry, with every line."
      },
      "JournalEntryFiling": {
        "type": "object",
        "properties": {
          "key": {
            "description": "Mast’s own key (`sales`, `bank`, `customer_invoice`, …); null for one the company made.",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string",
            "description": "In the company’s accounting language."
          }
        },
        "required": [
          "key",
          "name"
        ],
        "description": "A journal or a document type an entry is filed under."
      },
      "JournalEntryLine": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "lineNumber": {
            "type": "integer",
            "description": "Its rank in the entry, from 1."
          },
          "accountCode": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "debit": {
            "type": "number",
            "description": "In the base currency. One of `debit` and `credit` is 0."
          },
          "credit": {
            "type": "number",
            "description": "In the base currency."
          },
          "costCenterCode": {
            "description": "The code of the cost centre the line itself names; null with none, and for a line shared out between several. Read `costCenterShares` to sum by cost centre.",
            "type": [
              "string",
              "null"
            ]
          },
          "costCenterShares": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CostCenterShare"
            },
            "description": "How the line’s amount is shared out between cost centres: empty with none, one share at 100 for a line with one cost centre, several for a line shared out. A line can carry shares in more than one class at once: read one class at a time, each adds up to the line."
          },
          "lineType": {
            "description": "How Mast files the line (`revenue_base`, `vat_output`, `vat_input`, `cost_base`, `ar`, `ap`, `other`, …); null for a line that states none.",
            "type": [
              "string",
              "null"
            ]
          },
          "vatCode": {
            "description": "The VAT rate code the line was booked under.",
            "type": [
              "string",
              "null"
            ]
          },
          "vatRatePercent": {
            "type": [
              "number",
              "null"
            ]
          },
          "vatAmount": {
            "description": "On a VAT line: the tax it books, in the base currency.",
            "type": [
              "number",
              "null"
            ]
          },
          "taxableAmount": {
            "description": "The net amount the line’s VAT is computed on, in the base currency.",
            "type": [
              "number",
              "null"
            ]
          },
          "foreignAmount": {
            "description": "What the line moved in its account’s own currency, when that is not the base currency: positive on a debit, negative on a credit.",
            "type": [
              "number",
              "null"
            ]
          },
          "foreignCurrency": {
            "type": [
              "string",
              "null"
            ]
          },
          "counterpartyType": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "customer",
              "supplier",
              "employee",
              "product",
              null
            ]
          },
          "counterpartyId": {
            "description": "The customer’s, supplier’s, employee’s or product’s id in Mast.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "lineNumber",
          "accountCode",
          "description",
          "debit",
          "credit",
          "costCenterCode",
          "costCenterShares",
          "lineType",
          "vatCode",
          "vatRatePercent",
          "vatAmount",
          "taxableAmount",
          "foreignAmount",
          "foreignCurrency",
          "counterpartyType",
          "counterpartyId"
        ],
        "description": "A line of a journal entry."
      },
      "JournalEntryRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "number": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "number"
        ],
        "description": "Another entry, as an entry points to it."
      },
      "KeyAndCompany": {
        "type": "object",
        "properties": {
          "key": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The key’s id in Mast."
              },
              "name": {
                "type": "string",
                "description": "The name the key was given (« Back office »)."
              },
              "displayPrefix": {
                "type": "string",
                "description": "How the key starts, as Settings shows it: enough to tell it from another, never the key."
              },
              "roleName": {
                "type": "string",
                "description": "The role whose rights the key holds."
              },
              "expiresAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "When the key stops working; null for a key made never to expire."
              }
            },
            "required": [
              "id",
              "name",
              "displayPrefix",
              "roleName",
              "expiresAt"
            ]
          },
          "company": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The company’s id in Mast."
              },
              "name": {
                "type": "string",
                "description": "The company the key acts in. A key acts in one company and no other."
              }
            },
            "required": [
              "id",
              "name"
            ]
          },
          "connection": {
            "description": "Present when the caller is not a key but an assistant connected by sign-in (see the MCP page): `key` then holds the assistant’s name and the role of the person who connected it.",
            "type": "object",
            "properties": {
              "level": {
                "type": "string",
                "enum": [
                  "READ",
                  "PREPARE"
                ],
                "description": "What the connection may do: READ reads, PREPARE also prepares customers, products and draft invoices."
              },
              "connectedByName": {
                "type": "string",
                "description": "The person who approved the connection, whose rights it holds."
              }
            },
            "required": [
              "level",
              "connectedByName"
            ]
          }
        },
        "required": [
          "key",
          "company"
        ],
        "description": "An API key and the company it acts in."
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "paidOn": {
            "type": "string",
            "format": "date",
            "description": "The day the money came: the bank line’s booking day, else the day recorded."
          },
          "amount": {
            "type": "number",
            "description": "In the invoice’s currency."
          },
          "currency": {
            "type": "string"
          },
          "invoiceId": {
            "type": "string"
          },
          "invoiceExternalRef": {
            "type": [
              "string",
              "null"
            ]
          },
          "invoiceNumber": {
            "type": "string"
          },
          "customerId": {
            "type": "string"
          },
          "customerExternalRef": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "bank_line",
              "manual",
              "processor",
              null
            ],
            "description": "How it was recorded: a bank line matched to the invoice, by hand, or a payment processor’s charge. Null when Mast cannot tell."
          },
          "bankTransactionId": {
            "description": "The bank line’s id in Mast (`GET /ext/bank-transactions`), for a payment a bank line carries.",
            "type": [
              "string",
              "null"
            ]
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "paidOn",
          "amount",
          "currency",
          "invoiceId",
          "invoiceExternalRef",
          "invoiceNumber",
          "customerId",
          "customerExternalRef",
          "source",
          "bankTransactionId",
          "reference",
          "createdAt",
          "updatedAt"
        ],
        "description": "A payment received against an invoice. An invoice a payment processor’s own lane settled has none: its `amountPaid` says it. A payment cancelled in Mast drops out of the list."
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "externalRef": {
            "description": "Your own id of the product. Null for a product made in Mast.",
            "type": [
              "string",
              "null"
            ]
          },
          "number": {
            "type": "string",
            "description": "Mast’s own product number."
          },
          "type": {
            "type": "string",
            "enum": [
              "good",
              "service"
            ]
          },
          "name": {
            "type": "string"
          },
          "code": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "unitPrice": {
            "type": "number",
            "description": "The selling price, without VAT unless the invoice says its prices include it."
          },
          "costPrice": {
            "type": "number"
          },
          "currency": {
            "type": "string",
            "description": "The currency of its prices. An invoice line that takes the product's price takes the number as it is, in the invoice's own currency: nothing is converted."
          },
          "unit": {
            "type": [
              "string",
              "null"
            ]
          },
          "accountCode": {
            "description": "The revenue account a line of this product is booked to.",
            "type": [
              "string",
              "null"
            ]
          },
          "vatRateCode": {
            "description": "The product’s own VAT rate, by its code; null when it names none.",
            "type": [
              "string",
              "null"
            ]
          },
          "vatRatePercent": {
            "description": "That rate, in percent.",
            "type": [
              "number",
              "null"
            ]
          },
          "active": {
            "type": "boolean",
            "description": "False once a person deactivated it in Mast."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "externalRef",
          "number",
          "type",
          "name",
          "code",
          "description",
          "unitPrice",
          "costPrice",
          "currency",
          "unit",
          "accountCode",
          "vatRateCode",
          "vatRatePercent",
          "active",
          "createdAt",
          "updatedAt"
        ],
        "description": "Something the company sells."
      },
      "Supplier": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "externalRef": {
            "description": "Your own id of the supplier. Null for a supplier made in Mast that was never given one.",
            "type": [
              "string",
              "null"
            ]
          },
          "number": {
            "type": "string",
            "description": "Mast’s own supplier number."
          },
          "name": {
            "type": "string"
          },
          "businessType": {
            "type": "string",
            "description": "`corporation_company`, `sole_proprietorship`, `nonprofit_association`, `government_public`, `other`."
          },
          "registrationNumber": {
            "description": "Its number in the commercial register, as the company recorded it.",
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": "object",
            "properties": {
              "street": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postalCode": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": "string",
                "description": "The country’s name as Mast writes it."
              }
            },
            "required": [
              "street",
              "postalCode",
              "city",
              "country"
            ]
          },
          "vatStatus": {
            "type": "string",
            "enum": [
              "registered",
              "foreign_registered",
              "foreign_not_registered",
              "not_registered",
              "unknown"
            ],
            "description": "Whether the supplier is registered for VAT in the VAT territory of the company’s own country (`registered`), abroad (`foreign_registered`), or not; `unknown` when its record does not say."
          },
          "vatNumber": {
            "description": "Its VAT number in the company’s own VAT territory, for a supplier registered there.",
            "type": [
              "string",
              "null"
            ]
          },
          "foreignTaxId": {
            "description": "A foreign supplier’s own tax id.",
            "type": [
              "string",
              "null"
            ]
          },
          "foreignTaxIdCountry": {
            "description": "The country that gave that tax id (ISO 3166-1 alpha-2).",
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217: the currency its bills default to."
          },
          "paymentTermsDays": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "externalRef",
          "number",
          "name",
          "businessType",
          "registrationNumber",
          "email",
          "phone",
          "address",
          "vatStatus",
          "vatNumber",
          "foreignTaxId",
          "foreignTaxIdCountry",
          "currency",
          "paymentTermsDays",
          "createdAt",
          "updatedAt"
        ],
        "description": "A supplier of the company. No bank account is served, and none is written: a person enters it in Mast."
      },
      "TrialBalance": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "format": "date"
          },
          "to": {
            "type": "string",
            "format": "date"
          },
          "baseCurrency": {
            "type": "string"
          },
          "closingPeriod": {
            "type": "boolean",
            "description": "True for the year-end closing view: only the closing period’s entries are its movements."
          },
          "balanceSheetFrom": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The day asset, liability and equity accounts are summed from: the company’s first booked day, or `from` when nothing is booked."
          },
          "resultFrom": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The day income and expense accounts are summed from: the first day of the fiscal year `from` falls in, since they restart each fiscal year."
          },
          "provisionalOpeningUntil": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The last day of an earlier fiscal year still open: the opening balances can still change."
          },
          "isBalanced": {
            "type": "boolean",
            "description": "The closing debits and credits agree, `unplacedPriorYearsResult` counted."
          },
          "unplacedPriorYearsResult": {
            "type": "number",
            "description": "The result of earlier fiscal years that no row carries: 0 unless the company maps no account to the year’s result."
          },
          "totals": {
            "type": "object",
            "properties": {
              "openingDebits": {
                "type": "number"
              },
              "openingCredits": {
                "type": "number"
              },
              "periodDebits": {
                "type": "number"
              },
              "periodCredits": {
                "type": "number"
              },
              "closingDebits": {
                "type": "number"
              },
              "closingCredits": {
                "type": "number"
              }
            },
            "required": [
              "openingDebits",
              "openingCredits",
              "periodDebits",
              "periodCredits",
              "closingDebits",
              "closingCredits"
            ]
          },
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrialBalanceAccount"
            },
            "description": "By account code. Accounts with no balance and no movement are left out."
          }
        },
        "required": [
          "from",
          "to",
          "baseCurrency",
          "closingPeriod",
          "balanceSheetFrom",
          "resultFrom",
          "provisionalOpeningUntil",
          "isBalanced",
          "unplacedPriorYearsResult",
          "totals",
          "accounts"
        ],
        "description": "The figures of Mast’s own Trial Balance for the same days."
      },
      "TrialBalanceAccount": {
        "type": "object",
        "properties": {
          "accountId": {
            "type": "string"
          },
          "accountCode": {
            "type": "string"
          },
          "accountName": {
            "type": "string"
          },
          "accountType": {
            "type": "string",
            "enum": [
              "asset",
              "liability",
              "equity",
              "revenue",
              "expense"
            ]
          },
          "openingBalance": {
            "type": "number",
            "description": "What the account held when the period starts."
          },
          "periodDebits": {
            "type": "number",
            "description": "The movements dated inside the period. An opening-balance entry is none."
          },
          "periodCredits": {
            "type": "number"
          },
          "closingBalance": {
            "type": "number",
            "description": "What the account holds on the period’s last day."
          },
          "priorYearsResult": {
            "description": "On the account that carries the year’s result only: the result of earlier fiscal years not yet allocated, counted in its opening and closing balance.",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "accountId",
          "accountCode",
          "accountName",
          "accountType",
          "openingBalance",
          "periodDebits",
          "periodCredits",
          "closingBalance",
          "priorYearsResult"
        ],
        "description": "One account of the trial balance. Every figure is in the base currency and signed debit minus credit (a liability, equity or income account normally reads negative); `closingBalance = openingBalance + periodDebits - periodCredits`."
      },
      "VatRow": {
        "type": "object",
        "properties": {
          "ratePercent": {
            "type": "number"
          },
          "netAmount": {
            "type": "number"
          },
          "vatAmount": {
            "type": "number"
          }
        },
        "required": [
          "ratePercent",
          "netAmount",
          "vatAmount"
        ],
        "description": "One VAT rate of a document: the base it taxes and its VAT, as the PDF prints them."
      }
    }
  }
}
