Endpoints

PdfAPI exposes 13 endpoints across six controllers: document conversion, merge, and page extraction; tracking status and download; PDF inspection and validation; and a build-version endpoint. All 13 endpoints are attribute-routed; a convention route is registered but matched by no live action.

This page is the endpoint catalog and hub. Each controller's endpoints are documented in detail on its own page under endpoints/.

Route composition

Aspect	Finding
Routing mode	Both are registered — config.MapHttpAttributeRoutes() and the convention route api/{controller}/{id} (DefaultApi) — but every live action carries [Route], so only attribute routing resolves any action*
Convention template	api/{controller}/{id} — registered, matched by no live action*
Versioning	[RoutePrefix("v1")] / [RoutePrefix("v1/info")] / [RoutePrefix("v1/legacy")] on 11 of 13 endpoints; ApiInfoController carries no [RoutePrefix]
Base path	Application base URL (host + virtual directory) prefixed to every route below

A fully resolved route composes the controller's [RoutePrefix] with the action's [Route] fragment — for example [RoutePrefix("v1")] + [Route("convert")] → v1/convert. ApiInfoController carries no [RoutePrefix], so its route (buildVersion) carries no version segment.

Controller catalog

Controller	Route prefix	Base	Endpoints	Documentation
ConvertController	v1	ApiController	2	Details
ExtractController	v1	ApiController	1	Details
MergeController	v1	ApiController	1	Details
LegacyController	v1/legacy	ApiController	1	Details
InfoController	v1/info	ApiController	7	Details
ApiInfoController	—	ApiController	1	Details

Endpoint catalog

Exactly the required eight columns, in order. The Auth cell links to the service-wide authorization finding; the Rules cells link to business-rules.md.

Endpoint	Method	Route	Purpose	Request	Response	Auth	Rules
Convert (request body)	POST	v1/convert	Converts the document described by a ConvertRequest body to PDF or PDF/A, optionally tracking the request	PdfAPI.Core.ConvertRequest	PdfAPI.Core.PdfResult	None in code	BR-PDFAPI-017
Convert (raw bytes)	POST	v1/convert/{fileExtension}	Converts a raw document byte array to PDF or PDF/A using route and query parameters instead of a request wrapper	byte[] (raw body)	PdfAPI.Core.PdfResult	None in code	BR-PDFAPI-017
ExtractPages	POST	v1/extract	Extracts one or more page ranges from a source PDF into a new output document	PdfAPI.Core.ExtractPagesRequest	PdfAPI.Core.PdfResult	None in code	BR-PDFAPI-004, BR-PDFAPI-018
Merge	POST	v1/merge	Converts non-PDF inputs to PDF and merges all inputs into a single PDF output	PdfAPI.Core.MergeRequest	PdfAPI.Core.PdfResult	None in code	BR-PDFAPI-001, BR-PDFAPI-006, BR-PDFAPI-007
Download	GET	v1/legacy/download/{trackingId}	Downloads the output document for a previously tracked request, only when it succeeded	—	PdfAPI.Core.PdfResult	None in code	BR-PDFAPI-013
CheckPdfTrackingStatus	GET	v1/info/track/{trackingId}	Polls a tracking record's status, optionally sleeping and retrying while processing	—	PdfAPI.Core.PdfTrackingInfo	None in code	BR-PDFAPI-014
GetPageCount	POST	v1/info/pages/count	Returns the page count of a submitted PDF	byte[] (raw body)	int	None in code	BR-PDFAPI-005
HasFormFields	POST	v1/info/fields/exist	Reports whether a submitted PDF contains form fields	byte[] (raw body)	bool	None in code	BR-PDFAPI-021
FlattenFormFields	POST	v1/info/fields/flatten	Flattens the form fields in a submitted PDF and returns the flattened bytes	byte[] (raw body)	byte[]	None in code	BR-PDFAPI-021
IsPdf	POST	v1/info/validate	Reports whether the submitted bytes are a valid PDF	byte[] (raw body)	bool	None in code	BR-PDFAPI-005
IsPdfa	POST	v1/info/validate/pdfa	Reports whether a submitted PDF conforms to PDF/A	byte[] (raw body)	bool	None in code	—
Version	POST	v1/info/version	Returns the PDF version header found in a submitted document	byte[] (raw body)	string	None in code	BR-PDFAPI-005
GetBuildVersionData	GET	buildVersion	Returns build/version metadata for the deployed service	—	IEnumerable<KeyValuePair<string,string>>	None in code	—

Every route above is fully resolved: the v1, v1/info, and v1/legacy prefixes shown are each controller's [RoutePrefix] composed with its action's [Route] fragment. ApiInfoController carries no [RoutePrefix], so its route (buildVersion) is documented with no version segment, per source. Controller, action, and error-code detail for each endpoint moved to its controller detail page under endpoints/.

Error response shape

Two distinct facts about errors are documented across this API set and must not be conflated:

• Known, framework/action-level error detail. For the eight endpoints with no try/catch (InfoController's seven actions, ApiInfoController's one action), an uncaught exception is returned by the ASP.NET Web API framework with full exception detail, because IncludeErrorDetailPolicy.Always is set. For endpoints with a try/catch (ConvertController, ExtractController, MergeController, LegacyController), the action itself catches the exception and returns 200 OK with a failed PdfResult body instead of an HTTP error. This is the detail recorded in the Errors tables on each endpoint's detail page under endpoints/.
• Unknown outer envelope. Every response above — success or error — additionally passes through the globally registered ApiResponseHandler message handler (config.MessageHandlers.Add(new ApiResponseHandler());, PdfAPI\App_Start\WebApiConfig.cs), which wraps or post-processes the HTTP response for the whole service. ApiResponseHandler is supplied by the SAIF.Web.API NuGet package; its exact wrapping/envelope shape is implemented inside that package and is not visible in this repository. The endpoint and operation pages therefore describe only the pre-envelope detail — the final wire-level response body shape is unknown until resolved from the SAIF.Web.API package's own documentation.

Request flow diagram

The following diagram visualizes how a request reaches a handling action.

flowchart TD
    REQ["Client request"] --> ROUTE{"Attribute route match"}
    ROUTE -->|Match| A["Controller action"]
    ROUTE -->|No match| NF["404 Not Found"]
    A --> AUTH{"Authorization"}
    AUTH -->|None in code| OP["Service / business layer"]
    OP --> OK["200 OK"]
    OP --> ERR["500 Internal Server Error<br>(framework, uncaught exception)"]

Endpoints by operation

Endpoint	Operation
POST v1/convert	OP-CONVERT-REQUEST
POST v1/convert/{fileExtension}	OP-CONVERT-FILE
POST v1/extract	OP-EXTRACT-PAGES
POST v1/merge	OP-MERGE-DOCUMENTS
GET v1/legacy/download/{trackingId}	OP-DOWNLOAD-BY-TRACKING-ID
GET v1/info/track/{trackingId}	OP-CHECK-TRACKING-STATUS
POST v1/info/pages/count	OP-GET-PAGE-COUNT
POST v1/info/fields/exist	OP-HAS-FORM-FIELDS
POST v1/info/fields/flatten	OP-FLATTEN-FORM-FIELDS
POST v1/info/validate	OP-IS-PDF
POST v1/info/validate/pdfa	OP-VALIDATE-PDFA
POST v1/info/version	OP-GET-PDF-VERSION
GET buildVersion	OP-GET-BUILD-VERSION

Related documentation

• API index
• Overview
• Architecture
• 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\App_Start\WebApiConfig.cs
• PdfAPI\Controllers\v1\ConvertController.cs
• PdfAPI\Controllers\v1\ExtractController.cs
• PdfAPI\Controllers\v1\MergeController.cs
• PdfAPI\Controllers\v1\LegacyController.cs
• PdfAPI\Controllers\v1\InfoController.cs
• PdfAPI\Controllers\v1\ApiInfoController.cs