# Upload style examples from your own software

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. The fictional practice environment does not read files and does not prove this processing flow.

## Requirements

Use a production API key belonging to the user creating the style, with `stijlen:beheren` and `resultaten:lezen` for status. The account needs an integrations entitlement, room for a style, personal storage and actual credit processing. Charges belong to the linked user and remain subject to the key budget. A team style requires that user to be an administrator or team leader.

Keep the API key on your server. `RAPPORTLY_API_KEY` in the example is an environment variable. Never put keys in browser code, shared files or logs.

## 1. Submit the complete set of files

`POST https://api.rapportly.io/api/rapportly/v1/stijlprofielen`

Use multipart form data, with one to three files using the repeated field `bestanden`. Let your HTTP client set the multipart boundary.

| Required field | Value |
|---|---|
| `naam` | A name of 1–100 characters. |
| `soort` | `rapport`, `email`, `gespreksverslag`, `offerte` or `presentatie`. |
| `deling_scope` | `persoonlijk` (personal) or `team`. |
| `bevestigd` | The text `true`, confirming that processing may use credits. |
| `bestanden` | One to three example files, in the intended order. |

Store an `Idempotency-Key` with the request. A retry must use that same key and exactly the same fields, filenames, order and file bytes. Give a deliberate new task a new key.

```sh
curl --request POST 'https://api.rapportly.io/api/rapportly/v1/stijlprofielen' \
  --header "Authorization: Bearer $RAPPORTLY_API_KEY" \
  --header 'Idempotency-Key: crm-style-example-2026-0001' \
  --form-string 'naam=Fictitious report example' \
  --form-string 'soort=rapport' \
  --form-string 'deling_scope=persoonlijk' \
  --form-string 'bevestigd=true' \
  --form 'bestanden=@./fictitious-example.docx'
```

This is a shell example. Use the multipart method of your HTTP library in an application. Start with fictitious files.

A report style must begin with a DOCX or PDF. Regular document examples support PDF, DOCX, DOC, TXT or MD up to 20 MiB each. A presentation style starts with a presentation source, PDF or Word brand guide and allows up to 50 MiB per file. Keynote is rejected: export it to PowerPoint or PDF. Existing file safety and content checks decide whether a specific source is usable; an extension alone is insufficient.

## 2. Store the receipt and read status

A new complete receipt returns 202, with `id`, `opdracht_id`, `ontvangen:true`, `status:"bezig"` and `herhaald:false`. This confirms receipt for processing, not an approved or usable style.

```http
GET /api/rapportly/v1/stijlprofiel-uploads/<id>
Authorization: Bearer <production-key>
```

Use the original API key.

| Status | Next step |
|---|---|
| `upload_onvolledig` | Repeat the same complete request. No style profile is being processed yet. |
| `bezig` | Wait and poll again. A separate example review may be required. |
| `klaar` | Read the style and follow existing review/selection steps before using it for documents. |
| `mislukt` | Read existing style review and error details. Retrying the upload does not start another processing job. |
| `verlopen` | An incomplete upload is older than 30 days. Start a deliberate new request. |

An error may already contain `opdracht_id`; keep it for status reads. 404 means no receipt is confirmed for that key. If the entire HTTP response is lost, repeat the same complete request. Poll gently, for example every five seconds and less frequently later.

A successful replay returns 200 and the same ID. Replaying after deactivating or deleting the style returns 410 and never recreates it. Manual changes use the separate metadata/workshop routes and their current base version. Upload does not automatically change the team default.

## 3. Errors and retries

- 409 for different input under the same key: restore the original request or deliberately start a new one. Modified bytes are not a retry.
- 402 for a style limit or insufficient credits; 409 for insufficient storage. Resolve the specific limit and read the latest receipt before retrying.
- 403 for missing user, key or team permissions. Sending another user ID never grants access.
- 503 for temporarily unavailable processing/storage: preserve the task and key and retry unchanged. Do not automatically create a new task.
- Revoking or pausing the key stops new provider attempts and the first style publication. Actual costs already incurred remain charged. An already active style continues to use ordinary style permissions.

Incomplete uploads can be retried for 30 days. After that, Rapportly removes only those temporary files. Storage quota is released after confirmed deletion. Complete style sources are excluded from this cleanup.

Advanced reading/OCR, targeted recovery and the complete production OpenAPI will be documented separately for the combined release. This draft does not promise those additional routes yet.