# Cost estimates through the Rapportly API

This guide describes the available API within the documented release limits. Current key, user, package and object permissions remain required. Not every website feature is available through the API.

## Request

Use a production key with `gebruik:lezen` and `POST https://api.rapportly.io/api/rapportly/v1/generatieplan`. Headers: `Authorization: Bearer <your API key>` and `Content-Type: application/json`. Keep the key on your server. An Idempotency-Key is not required for this read-only calculation; repeating it does not start processing.

```json
{
  "soort": "rapport",
  "tier": "standaard",
  "invoerBytes": 18000,
  "bestanden": 1,
  "tweedeTaal": false,
  "generatieOpties": {
    "versie": 1,
    "route": "automatisch",
    "begeleidendeBrief": false
  }
}
```

Required `soort`: `rapport`, `offerte` or `bundel` (conversation bundle), matching the three kinds supported by this website estimate. Presentations are outside this generation plan. `tier`: `basis`, `standaard` or `max`; a locked team level takes precedence. Optional `invoerBytes` and `bestanden` are integers from 0 through 1,000,000,000. Send counts, not document content.

Optional `stijlprofielId` is the UUID of an active personal or shared style. Rapportly derives the section count itself. `tweedeTaal` is boolean. For quotes only, `vasteOfferte` and `offerteVoorstel` are booleans describing the intended processing; they do not change an existing task. `generatieOpties.route` accepts `automatisch`, `efficient` or `uitgebreid`. You cannot force the automatic selection through a hidden field. Unknown fields and URL query parameters are rejected.

## Using the response

Personal credit mode returns `creditsVan`, `creditsTot`, effective `tier`, `stappen`, `onzekerheden`, `volledig`, `geraamdOp` and `grondslag: werkbegroting_geen_maximum`. Each step has an estimated credit range. Word/PDF formatting uses zero AI credits in this calculation. Files may incur unknown OCR/reading costs: show `onzekerheden` and do not treat `volledig: false` as a complete estimate.

The API also returns `raming: true`, `verwerking_gestart: false` and `credits_afgeboekt: 0`. This request reserves no credits, guarantees no maximum price and grants no permission to start. Starting later rechecks the user, key permissions, sources, available credits and budgets. Actual usage remains authoritative. Later estimates may change with settings or prices. For `creditmodus: legacy`, this endpoint only supplies the generation plan; absent amounts do not mean free processing.

## Errors and recovery

- 400: invalid kind, fields, types or options. Correct the request.
- 401/403: the key, user permissions or integrations plan do not permit access.
- 404: the style does not exist or this user cannot read it.
- 409 `api_generatieplan_stijl_gewijzigd`: the style version changed during calculation. Read the style again and request a new estimate.
- 503: reliable pricing or an estimate is unavailable. Do not invent a number; try again later.

This estimate does not read dossier contents or start provider processing. If displayed in your software, retain it only as an indication with its timestamp. Request a current estimate before an intentional start when appropriate.