# Architecture > How ReportingCloud works: the REST Web API below api.reporting.cloud/v1, HTTPS and CORS, the portal, template storage, the merge process, SDKs and Azure. - **Product:** ReportingCloud - **Section:** Documentation - **Kind:** Topic - **Path:** ReportingCloud > Overview > Architecture - **2416 words** - **Web URL:** https://docs.textcontrol.com/reporting-cloud/overview/architecture/ - **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/overview/architecture/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/overview/architecture/llms-full.txt --- What happens between your application's request to ReportingCloud and the PDF that comes back? The service has three public parts, the Web API, the ReportingCloud portal and the status page, and the Web API and the portal share one template storage per account. Knowing how they connect, and which part runs where, helps you decide where templates live and what your own code has to do. The sections below follow a merge request through the service. ### Architecture at a Glance ```text Your side Text Control, hosted on Microsoft Azure Backend, script or SDK --HTTPS, JSON----> Web API https://api.reporting.cloud/v1/ | +--> TX Text Control document engine | +--> Template storage of your account ^ | Browser: you and your --HTTPS----------> Portal https://portal.reporting.cloud/ template designers template editor, datasource excerpts, API keys, transactions, statistics Browser --HTTPS----------> Status page https://status.reporting.cloud ``` - **Only your client runs on your side.** Your backend, a script or one of the SDKs sends the requests. The document engine, the storage and the portal run at Text Control. - **One account, one storage.** A template that you upload or design in the portal is the template that a merge request names, and a template uploaded with the Web API appears in the portal. - **HTTPS everywhere.** The Web API, the portal and the status page are reached over HTTPS. ### The Web API The Web API is a REST API at the base address `https://api.reporting.cloud/`. Every endpoint is below the version path `/v1/`, for example `https://api.reporting.cloud/v1/document/merge`, and is called with one of the HTTP methods `GET`, `POST`, `PUT` or `DELETE`. The reference groups the endpoints like this: | Group | Endpoints | What they do | |---|---|---| | [Document](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/llms-full.txt) | `document/merge`, `convert`, `append`, `findandreplace`, `thumbnails`, `share` | Create, convert and combine documents, render pages as images and share documents | | [Templates](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/llms-full.txt) | `templates/upload`, `list`, `count`, `exists`, `info`, `pagecount`, `download`, `thumbnails`, `delete` | Manage the template storage and read what a template contains | | [Account](https://docs.textcontrol.com/reporting-cloud/reference/web-api/account/llms-full.txt) | `account/settings`, `apikeys`, `apikey` | Read your quotas and manage your API keys | | [Fonts](https://docs.textcontrol.com/reporting-cloud/reference/web-api/fonts/llms-full.txt) | `fonts/list` | List the fonts that templates can use | | [Proofing](https://docs.textcontrol.com/reporting-cloud/reference/web-api/proofing/llms-full.txt) | `proofing/check`, `suggestions`, `availabledictionaries` | Check spelling and suggest corrections | | [Processing](https://docs.textcontrol.com/reporting-cloud/reference/web-api/processing/llms-full.txt) | `processing/review/trackedchanges`, `removetrackedchange` | List, accept and reject tracked changes | How requests and responses are built: - **JSON in and out.** A request body is JSON: a body object such as `MergeBody`, or a document as a Base64 string. A response carries documents and images as Base64 strings, for example an array with one string per merged document. - **Query parameters** set the options of a request, such as `returnFormat`, `templateName` and `test`. - **HTTPS only.** The Web API is served over HTTPS. A plain HTTP connection to `api.reporting.cloud` on port 80 isn't answered. - **Authentication.** Every request carries an `Authorization` header, either with an API key (`ReportingCloud-APIKey`) or with the user name and password of the account (`Basic`). [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt) shows both. - **CORS.** The Web API answers with the header `Access-Control-Allow-Origin: *`, so JavaScript on a web page of any origin may call it. A script in the browser has to send your credentials, though, which makes them visible to the users of the page. [Data Security and Privacy](https://docs.textcontrol.com/reporting-cloud/overview/security/#credentials-and-api-keys) explains how to keep them on your server. - **Limits.** The endpoints that create documents or thumbnails limit the processing time of a request to 60 seconds and cancel the task after that. A typical document takes less than 5 seconds. A merge request is refused when more than two requests of the same account come in at the same time. [Errors and Status Codes](https://docs.textcontrol.com/reporting-cloud/document-processing/errors/llms-full.txt) lists the responses. ### The Portal The portal at `https://portal.reporting.cloud/` is where you manage what the Web API uses. Its dashboard shows your recent activities, the service status and your quota usage. In the portal, you: - upload, create, edit and delete the templates of your storage, and copy samples from the Sample Template Gallery into it; - design templates in the template editor, the MS Word compatible editor of TX Text Control, which takes its lists of merge fields and merge blocks from a datasource excerpt; - create and edit datasource excerpts, sample JSON in the format of your merge data; - manage your subscription and your API keys, and see your quota settings; - follow the transactions of the current month in the Transaction Monitor and the monthly usage in Statistics. With the Extreme plan, you can also create groups of templates and invite external template designers into them. [Portal](https://docs.textcontrol.com/reporting-cloud/portal/llms-full.txt) describes each page. ### Template Storage Each account has a template storage that the Web API and the portal share. A merge or find and replace request takes its template from the storage or from its own body: | | Template in the storage | Template sent with the request | |---|---|---| | How | You upload it once, in the portal or with `templates/upload`, and name it in the `templateName` parameter | You put it into the `template` property of the request body, `MergeBody` or `FindAndReplaceBody`, as a Base64 string | | Speed | Faster, because the template doesn't travel with each request | The template is uploaded with every request | | Quota | Counts against the templates in storage of your plan | Doesn't count against the template storage | | What happens to it | Stays in your storage until you delete it | Unpacked in memory, merged and deleted after the merge. It is never stored. | | Endpoints | `document/merge`, `document/findandreplace`, `document/share` and the `templates/` endpoints | `document/merge`, `document/findandreplace` | Text Control recommends the storage for templates that you merge again and again. The other endpoints of the Document group, `POST /v1/document/convert`, `POST /v1/document/append` and `POST /v1/document/thumbnails`, as well as the tracked changes endpoints, take the document in the request body and don't use the storage. [Template Storage](https://docs.textcontrol.com/reporting-cloud/portal/templates/llms-full.txt) covers the storage in the portal, and [Managing Templates](https://docs.textcontrol.com/reporting-cloud/document-processing/templates/llms-full.txt) covers its endpoints. ### How a Merge Request Is Processed ![Invoice template with merge fields and JSON data sent to /v1/document/merge, which returns the merged PDF invoice](https://docs.textcontrol.com/assets/img/reporting-cloud/template-json-merge-concept.82a0c7c8.webp) A merge is the most common request. It runs through these steps: 1. Your application sends `POST /v1/document/merge` with the `returnFormat` parameter and either the `templateName` parameter or the template in the request body. The `mergeData` property of the body holds the data: a JSON array with one object per record, or a single object for one record. 2. ReportingCloud loads the template from your storage, or decodes the template that came with the request. 3. The engine fills each merge field with the value of the JSON property of the same name, and repeats each merge block for the items of the array of the same name. 4. The response is a JSON array of Base64 strings. By default, the documents of all records are appended into one; with `append=false`, every record becomes a document of its own. 5. The merge data and the created documents are not kept. ReportingCloud logs the metadata of the transaction, from which the portal shows the transaction and counts your document quota. [Overview](https://docs.textcontrol.com/reporting-cloud/mail-merge/overview/llms-full.txt) in the Mail Merge section describes merging in detail. ### SDKs The SDKs for .NET, PHP, Java and Ruby are wrappers around the Web API: they send the HTTP requests the reference describes and give you classes and methods to manage templates and merge documents. The endpoints, limits and quotas described above apply to them in the same way. [SDKs](https://docs.textcontrol.com/reporting-cloud/sdks/llms-full.txt) compares them, and [Installing an SDK](https://docs.textcontrol.com/reporting-cloud/installation/sdks/llms-full.txt) installs them. ### Hosting and Availability - **Microsoft Azure.** ReportingCloud is hosted on Microsoft Azure. Where your data is processed is described in [Data Security and Privacy](https://docs.textcontrol.com/reporting-cloud/overview/security/#hosting-and-data-location). - **Status page.** `https://status.reporting.cloud` shows the availability of three areas, the Web API, the portal and the backend, and lists reported incidents with their updates. - **Maintenance.** In the services agreement, Text Control commits to reasonable efforts to keep the service available 24 hours a day, 7 days a week, and states that maintenance, updates and repairs can interrupt it. - **Hosting it yourself.** The services agreement asks you to contact Text Control if you want to host your own ReportingCloud service. For document processing on your own servers, Text Control offers [DS Server](https://docs.textcontrol.com/ds-server/overview/introduction/llms-full.txt). ### Based on TX Text Control The Web API and the portal run on TX Text Control, and the portal's template editor is the HTML5 editor of TX Text Control .NET Server. Text Control has moved the service to new TX Text Control releases: X14 Service Pack 1 reached the portal and the Web API in February 2017, X15 in January 2018 and X16 in January 2019. It has been updated since: the PDF documents that the service created in October 2026 name `tx_pdf 28.0.353.500`, TX Text Control 28.0, as their producer. The blog article [ReportingCloud: Backend Updated to TX Text Control X16](https://www.textcontrol.com/blog/2019/01/03/impact-of-the-azure-reboot-strategy/) describes the upgrade to X16, and [Older Versions](https://docs.textcontrol.com/reporting-cloud/whats-new/older-versions/llms-full.txt) in What's New lists what each one brought. ### Next Steps - [Supported File Formats](https://docs.textcontrol.com/reporting-cloud/overview/file-formats/llms-full.txt): the formats each endpoint reads and returns. - [Data Security and Privacy](https://docs.textcontrol.com/reporting-cloud/overview/security/llms-full.txt): what the service stores and where it runs. - [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt): the two ways a request authenticates. - [Portal](https://docs.textcontrol.com/reporting-cloud/portal/llms-full.txt): the pages of the portal. - [Web API](https://docs.textcontrol.com/reporting-cloud/reference/web-api/llms-full.txt): every endpoint with its parameters and responses. --- ## Nearby - **Previous:** [Introduction](https://docs.textcontrol.com/reporting-cloud/overview/introduction/llms-full.txt) - **Next:** [Supported File Formats](https://docs.textcontrol.com/reporting-cloud/overview/file-formats/llms-full.txt)