Your documents.
Your way to send them.

01 / THE WORKFLOW

Prepare. Review. Confirm.

Uploading and preparation do not trigger any communication. Once the beta is open, first create your Guteneo workspace in the browser and verify your email address. Then connect a registered OAuth client with the required permissions.

1. Upload the PDF. Send the original file in the field file. Wait for its status to become ready : a 201 response may still refer to a quarantined document.
2. Prepare the dispatch. Choose the document and recipient. Keep the response, its id, its fingerprint and the returned amounts. Any spending limit you set is in EUR cents.
3. Standard approval. Direct the person to https://guteneo.com/#/app/dispatch/{id}. They review the PDF, recipient, options and cost, then approve in their Guteneo session. Optional expert mode follows a limited mandate enabled beforehand in My account for the relevant assistant.
4. Confirm and track. The client can then call POST /api/dispatches/{id}/confirm, with an idempotency key specific to this confirmation. Then read the dispatch status again.

curl 'https://guteneo.com/api/documents' \
  --header "Authorization: Bearer $GUTENEO_ACCESS_TOKEN" \
  --form 'file=@./document.pdf;type=application/pdf'

curl 'https://guteneo.com/api/dispatches' \
  --header "Authorization: Bearer $GUTENEO_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ma-preparation-unique-001' \
  --data '{
    "channel": "fax",
    "documentId": "doc_identifiant_recu",
    "recipient": { "phone": "+33199001234" }
  }'

These examples are request templates, not provided credentials. The environment variable contains an access token obtained by your OAuth client; never put it in a URL or code repository. No example is executed from this page.

The REST result is the raw dispatch. The field approvalUrl belongs to the MCP response; in REST, build the browser link using the returned identifier. A yes in a conversation and tool permission create neither human approval nor an expert mandate. The expert MCP flow uses a recent review followed by delegated approval; it respects the mandate’s limits and your assistant’s confirmations.

For postal mail, first read the template with GET /api/postal/requirements?country=LU, specifying the recipient’s country. After creating and importing the PDF, use POST /api/postal/preflights : Guteneo checks the exact PDF and returns a reviewUrl. In standard mode, the person opens this link to review the pages and authorise transfer to the printing provider. Expert mode requires a postal mandate that separately covers this data transfer; it does not trigger any dispatch. After the draft has been analysed, request POST /api/postal/preflights/{id}/quote, then have the quote approved. These steps remain separate from sending; an uncertain transfer must never be retried automatically.

02 / AUTHENTICATION

Precise permissions.

Clients use Authorization Code with PKCE S256, an exactly registered redirect URI and a verified parameter state . The audience is https://guteneo.com/mcp, including for the documented REST routes. There is no personal API key or password to share with an assistant.

Authorisation

https://pieper.eu.auth0.com/authorize

Code exchange

https://pieper.eu.auth0.com/oauth/token

HTTP token

Authorization: Bearer <access_token>

Use an access token, never an ID token. A public client contains no client secret. The organisation is determined by membership and the authorised connection; no parameter allows freely selecting another workspace. With multiple workspaces, the link is set in the dashboard’s connections. The reader role forbids writes, even with a scope. During the beta, all roles require a verified account; two-factor authentication is not mandatory.

No scope authorises human approval. The browser approval route, administration and billing are not part of this developer API. OAuth permissions do not replace role, sender, credit or channel checks.

For assistants, the intended transport is MCP Streamable HTTP at https://guteneo.com/mcp. Integration files are available in the installation instructions. Each client still needs to be registered and tested in its real environment.

03 / DOCUMENTS

An original stays an original.

POST /api/documents preserves the uploaded bytes. The PDF is private, identified by its SHA-256, and undergoes scanning and validation in an isolated environment. GET /api/documents/{id}/content returns only a ready document, with the header X-Document-SHA256 and no public caching.

POST /api/documents/render creates a new A4 PDF from sanitised HTML. Scripts, supplied styles and external resources are removed. This rendering must not be used to reconstruct an original from its text. URL import is restricted to the MCP tool import_document, on any public HTTPS domain, without redirects; it is not a REST route.

The field analysis shows whether the check is in progress, complete, needs a retry or is blocked, with an explanation and a next action. While a check is in progress, query GET /api/documents/{id} no more often than every 15 seconds. The server handles limited automatic retries. Offer an explicit retry via POST /api/documents/{id}/rescan only when the returned action is rescan. Keep the same document: no new upload is needed.

04 / RELIABILITY

One request, one dispatch.

The header Idempotency-Key is required for preparation and confirmation: 1 to 200 characters, with no newline or NUL character. Keep a stable key for each logical operation; use a different key for confirmation. Reusing a key with different content produces IDEMPOTENCY_CONFLICT.

The fingerprint fingerprint binds the approved content, recipient, document, options and cost. Approval lasts at most 15 minutes and may expire earlier with the quote. Confirmation reserves the spending limit and inserts the work to be done in the same transaction.

curl 'https://guteneo.com/api/dispatches/dsp_identifiant_recu' \
  --header "Authorization: Bearer $GUTENEO_ACCESS_TOKEN"

• prepared : preparation saved, not yet queued.
• queued : confirmation accepted, work pending.
• submitting / submission_unknown : the provider may already have received the request. No automatic retry or new replacement dispatch.
• accepted : accepted by the provider; this is not proof of delivery. Check the subsequent events.

After an HTTP timeout, first read the dispatch again. Cancellation is possible only before submission starts, for prepared or queued. CANCELLATION_TOO_LATE means cancellation is no longer guaranteed.

Responses always distinguish between mode: simulation and production. Balances and spending limits are integers in EUR cents. A fractional quote also exposes quote_customer_nanoeur : 1 EUR equals one billion nanoEUR. Charges in cents follow the organisation’s exact cumulative total, without rounding each email up to one cent. These fields may be absent from lists or null; this does not mean a zero price.

For fax v3, faxPricing provides the price range excluding tax in nanoEUR and the firm spending limit in cents. The limit is reserved at confirmation. Then check settlement.status : delivery may be complete while settlement is still reserved. Only settled provides validated usage and the balance debit. The qualified rate limits faxes to a maximum of ten pages, even if the PDF was successfully imported.

In production, each channel requires qualified private pricing and a quote that is still valid. No provider amount supplied by the client can replace them. The indicative homepage rates are not an API quote.

05 / LIMITS AND ERRORS

Plan for waiting states.

PDF

10 MiB · 100 pages maximum

Email HTML and text

128 KiB UTF-8 per content

CSV

256 KiB · 500 rows maximum

Lists

30 items by default · 100 maximum

Authenticated API

180 requests per minute per organisation

PDF rechecks

10 per day per organisation

Uploads and renders also have daily quotas specific to the organisation. Lists return items and nextCursor ; send this opaque cursor back unchanged. CSV validation responses separate rows, errors and duplicates : HTTP success does not mean every row is valid.

An error contains { "error": { "code", "message" } }, sometimes a list fields. Keep the code and X-Correlation-ID for diagnostics, without logging the document, recipient or token.

• 401 / 403 : authentication or permission; ONBOARDING_REQUIRED requires signing in through the browser first.
• 409 : incompatible approval, quote, credit, quota or status. Correct the cause; do not change the key to force a dispatch.
• 413 / 423 : content too large or document cannot be viewed.
• 429 : slow down. The HTTP limit returns Retry-After: 60 ; document quotas do not necessarily include this header.
• 503 : required configuration or service unavailable. The public demo instead returns 403 PREVIEW_ONLY.

GET /api/usage distinguishes welcome credit, reservations and monthly limits. The credit does not renew. An unknown provider outcome keeps the reservation; it never justifies an automatic resend.