ConvertController

ConvertController exposes two overloads of document conversion: a request-object form that carries a Document inside ConvertRequest, and a raw-body form that takes the file bytes directly with the extension and target format as separate parameters.

Field	Value
Controller	ConvertController
Base	System.Web.Http.ApiController
Route prefix	[RoutePrefix("v1")]
Source	PdfAPI\Controllers\v1\ConvertController.cs
Controller-level authorization	None in code
Error handling	Per-action try/catch + ILogService.LogException; response then passes through ApiResponseHandler, whose final outer envelope is unknown** (details)
Endpoints	2

---

POST v1/convert

Converts the document described by a ConvertRequest body to PDF or PDF/A, tracking the request when tracking is enabled, and returns the result whether the conversion succeeded or failed.

Field	Value
HTTP verb	POST
Resolved route	v1/convert
Route composition	[RoutePrefix("v1")] + [Route("convert")]
Action	Convert(ConvertRequest request)
Return type	IHttpActionResult (Ok(result))
Authorization	None in code
Idempotent	No — each call creates a new tracking record and produces a new output document*
Operation	OP-CONVERT-REQUEST

Convert request parameters

Name	In	Type	Required	Default	Binding	Purpose
request	Body	PdfAPI.Core.ConvertRequest	Yes	—	Implicit complex-type body binding*	The source document and conversion options

Convert request

Field	Value
DTO	PdfAPI.Core.ConvertRequest (PdfAPI.Core\Request\ConvertRequest.cs)
Media type	application/json
Validation	None beyond model binding

Property	Type	Required	Constraints	Purpose
File	byte[]	Yes	—	The source document bytes
FileExtension	string	Yes	—	Source document extension used to select the conversion path
Format	via Options.OutputFormat	No	PdfFormat.Pdf | PdfFormat.PdfA	Requested output format
SkipPdf	bool	No	Default true	When true and the input is already a PDF, conversion is short-circuited (BR-PDFAPI-019)
TrackingEnabled (inherited from PdfRequest)	bool	No	Default true; forced true when SendHeatEmailOnFailure is set	Enables persistence of a tracking record
SendHeatEmailOnFailure (inherited)	bool	No	—	Sends a failure incident email (BR-PDFAPI-015)

Convert response

Field	Value
DTO	PdfAPI.Core.PdfResult
Media type	application/json

Property	Type	Nullable	Purpose
Status	PdfStatus	No	Terminal or non-tracked status of the conversion
Message	string	Yes	Failure detail when Status indicates failure
Document	Document	Yes	The converted output document
TrackingId	value type	Yes	Identifier for later status check or download

Convert status codes

Status	Condition	Body
200 OK	Returned for both a successful conversion and a caught failure (BR-PDFAPI-017)	PdfResult

Convert errors

Error status	Trigger	Produced by	Body
500 Internal Server Error	request is null — request.ToString() inside the catch throws NullReferenceException, escaping the action*	Framework (uncaught exception, IncludeErrorDetailPolicy.Always)	Exception detail (message, type, stack trace)
400 Bad Request	Request body fails to deserialize into ConvertRequest*	Framework (model binding, before the action is entered)	Framework default validation body

The Body column above describes only the pre-envelope detail produced by the framework or action. Every response also passes through the globally registered ApiResponseHandler message handler (SAIF.Web.API package), which wraps or post-processes the HTTP response for the whole service. That handler's exact outer envelope shape is implemented inside the package and is not visible in this repository — see Endpoints: Error response shape.

Convert business rules

• BR-PDFAPI-017 — a processing failure is returned as a 200 OK carrying a failed PdfResult, not an HTTP error.
• BR-PDFAPI-019 — when SkipPdf is set (the default) and the input is already a PDF, conversion is short-circuited.
• BR-PDFAPI-015 — a failed conversion sends an incident email only when SendHeatEmailOnFailure is set.
• BR-PDFAPI-010 — TrackingEnabled is forced on whenever SendHeatEmailOnFailure is set, regardless of the caller's value.

Authorization (POST v1/convert)

No authorization attribute or programmatic check is present on ConvertController or this action. See Authentication and authorization for the service-wide finding.

Side effects and idempotency (POST v1/convert)

Aspect	Finding
Records written	PDFTracking (see Data model) — inserted when TrackingEnabled, updated on completion
Downstream calls	Incident email via SMTP when SendHeatEmailOnFailure is set and the result failed
Files or messages produced	Converted output document written to pdfapi.rootdirectory
Repeat-call behavior	Each call creates a new tracking record and a new output document; there is no deduplication on this path*

Example (POST v1/convert)

POST v1/convert HTTP/1.1
Host: <host>
Content-Type: application/json

{
  "File": "<base64 bytes>",
  "FileExtension": "docx",
  "Options": { "OutputFormat": "Pdf" }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Status": "Succeeded",
  "TrackingId": 12345,
  "Document": { "FileName": "output.pdf" }
}

---

POST v1/convert/{fileExtension}

Converts a raw document byte array supplied in the request body, using route and query parameters for the source extension and target format, rather than a ConvertRequest wrapper.

Field	Value
HTTP verb	POST
Resolved route	v1/convert/{fileExtension}
Route composition	[RoutePrefix("v1")] + [Route("convert/{fileExtension}")]
Action	Convert(byte[] file, string fileExtension, PdfFormat format)
Return type	IHttpActionResult (Ok(result))
Authorization	None in code
Idempotent	No — each call produces a new output document*
Operation	OP-CONVERT-FILE

Convert by extension parameters

Name	In	Type	Required	Default	Binding	Purpose
file	Body	byte[]	Yes	—	[FromBody]*	The raw source document bytes
fileExtension	Route	string	Yes	—	Route segment	Source document extension used to select the conversion path
format	Query	PdfFormat	No	PdfFormat.Pdf	[FromUri]*	Requested output format

Convert by extension request

Field	Value
DTO	— (raw byte[] body)
Media type	application/json (byte array serialized as base64)
Validation	None beyond model binding

Convert by extension response

Field	Value
DTO	PdfAPI.Core.PdfResult
Media type	application/json

Property	Type	Nullable	Purpose
Status	PdfStatus	No	Terminal or non-tracked status
Document	Document	Yes	Converted output document

Convert by extension status codes

Status	Condition	Body
200 OK	Success or caught failure — all in-action exceptions are caught and surfaced as Status = Failed	PdfResult

Convert by extension errors

Error status	Trigger	Produced by	Body
500 Internal Server Error	None identified — all in-action exceptions on this path are caught	Framework, if a non-caught failure occurs	Exception detail

The Body column above describes only the pre-envelope detail produced by the framework, should this uncaught case occur. Every response also passes through the globally registered ApiResponseHandler message handler (SAIF.Web.API package), which wraps or post-processes the HTTP response for the whole service. That handler's exact outer envelope shape is implemented inside the package and is not visible in this repository — see Endpoints: Error response shape.

Convert by extension business rules

• BR-PDFAPI-017 — a processing failure is returned as a 200 OK carrying a failed PdfResult, not an HTTP error.

Authorization (POST v1/convert/{fileExtension})

No authorization attribute or programmatic check is present. See Authentication and authorization.

Side effects and idempotency (POST v1/convert/{fileExtension})

Aspect	Finding
Records written	PDFTracking, when tracking is enabled for the constructed request*
Downstream calls	None identified
Files or messages produced	Converted output document written to pdfapi.rootdirectory
Repeat-call behavior	Each call produces a new output document; no deduplication identified*

Example (POST v1/convert/{fileExtension})

POST v1/convert/docx?format=Pdf HTTP/1.1
Host: <host>
Content-Type: application/json

"<base64 bytes>"

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Status": "Succeeded",
  "Document": { "FileName": "output.pdf" }
}

---

Related documentation

• API index
• Overview
• Architecture
• Endpoints
• Authentication and authorization
• Dependencies
• Configuration
• Operations and processes
• Business rules
• Data model
• Operational runbook
• Tech debt

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

• PdfAPI\Controllers\v1\ConvertController.cs
• PdfAPI.Core\Request\ConvertRequest.cs
• PdfAPI.Core\Request\PdfRequest.cs
• PdfAPI.Core\PdfResult.cs