Analyze a PDF document from a publicly accessible URL to detect modifications and tampering.
POST https://api.htpbe.tech/v1/analyze
This endpoint requires API key authentication via the Authorization header.
Authorization: Bearer YOUR_API_KEYEach call draws from a single pool shared by API calls and web uploads. A subscriber's monthly quota is spent first; once it is used up, calls draw from any one-time credit packs on the account.
When a subscriber reaches their quota with no credit pack left — or a key has no credits and no active subscription — the call returns 402 PAYMENT_REQUIRED. Add a one-time credit pack or upgrade your plan to continue. Continued checking past the monthly quota ("overage") is not enabled by default; it is available only by individual agreement.
Every check that returns a result uses one credit or quota unit — including an inconclusive result with status_reason: "analysis_incomplete" (see Analysis Interrupted). A request that ends in an error and returns no result uses nothing. That includes an analysis stopped by a fault on our side: it returns the Analysis Interrupted error, never a partial result.
What uses a credit and what does not:
- Reading a result again with
GET /result/{id}never uses a credit, however often you read it. - Replaying a request with its original
Idempotency-Keyand the sameurlreturns the originalidwithout analysing the file again and without using another credit (see Idempotent Retries). It returns the same result, so it is not a way to have a file checked again. - Submitting the file again — with no
Idempotency-Keyor with a new one — is a new analysis. It may use another credit or quota unit under the same rules as the first, including when the earlier result wasanalysis_incomplete.
If a request times out, or your connection drops after you sent it, you cannot tell from the client side whether the server already processed it. Retrying blindly risks spending credit twice for the same document.
Send an Idempotency-Key header (any string you generate, up to 255 characters — a UUID is a good choice) with a request you might need to retry. Reuse the exact same value when you retry that same logical request:
- If the original request already completed successfully, the retry returns
201with the same checkid— no credit is spent again, and the document is not re-analyzed. This includes a result that came back withstatus_reason: "analysis_incomplete": the replay returns that same result. Sending the file with a new key is a new analysis, not a retry, and may use another credit or quota (see Quota & Credits). - If the original request is still being processed, the retry returns
409with error codeidempotency_key_in_progress. Wait and retry with the same key — changing the key would start a second, independently-charged request. - If the original request failed (and its credit hold was released), the retry proceeds as a normal new request.
- If the same key is sent again with a different
url, the request is rejected with422and error codeidempotency_key_fingerprint_mismatch— a key identifies one logical request for one document, never a pool of documents. Generate a new key for a new document.
The key is scoped to your account and request source (a live API key and a web-app session for the same account are separate scopes) — a different account, or a different key on the same account made through a different source, can reuse the same string without colliding with yours. Two live API keys on the same account share this scope. Omitting the header is fully supported: your request is processed exactly as it is today, with no idempotency guarantee.
Test keys (htpbe_test_...) ignore the header: test requests spend no credit and always return the same synthetic id for a given test URL, so none of the outcomes above (409, 422 idempotency_key_fingerprint_mismatch) can occur with a test key.
curl -X POST https://api.htpbe.tech/v1/analyze \
-H "Authorization: Bearer htpbe_live_sk_1234567890abcdef" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c2f6b6e-1a3d-4b8a-9c3a-2e6f1d9b4a10" \
-d '{
"url": "https://example.com/documents/contract.pdf"
}'| Header | Type | Required | Description |
|---|---|---|---|
Authorization |
string | Yes | Bearer token with your API key (Bearer htpbe_live_... or Bearer htpbe_test_...). The Bearer prefix is recommended but optional — sending the raw key directly is also accepted, but only if the key starts with htpbe_ (e.g., Authorization: htpbe_live_sk_...). |
Content-Type |
string | Yes | Must be application/json |
Idempotency-Key |
string | No | A key you generate (up to 255 characters) that makes a retry of the exact same logical request safe — see Idempotent Retries below. |
| Parameter | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | Publicly accessible HTTP/HTTPS URL pointing to a PDF file. The file must be downloadable without authentication and must not exceed 10 MB in size. |
original_filename |
string | No | Original filename of the document (before any storage renaming). When provided, this name is stored and returned in results instead of the filename extracted from the URL. |
Format: Must be a valid HTTP or HTTPS URL
File Size Limit: Maximum 10 MB (10,485,760 bytes)
Accessibility: The URL must be publicly accessible. Files behind authentication, firewalls, or VPNs will fail to download.
Valid Examples:
https://example.com/documents/contract.pdfhttps://cdn.yoursite.com/uploads/2024/invoice-12345.pdfhttps://storage.googleapis.com/bucket-name/file.pdf
Invalid Examples:
http://localhost/document.pdf(not publicly accessible)https://example.com/file.docx(not a PDF)ftp://example.com/file.pdf(FTP not supported)file:///local/path/document.pdf(local file paths not supported)https://user:password@example.com/file.pdf(credentials in the URL are not supported)
curl -X POST https://api.htpbe.tech/v1/analyze \
-H "Authorization: Bearer htpbe_live_sk_1234567890abcdef" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/documents/contract.pdf"
}'// Node.js / TypeScript
const response = await fetch('https://api.htpbe.tech/v1/analyze', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HTPBE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://example.com/documents/contract.pdf',
}),
});
const result = await response.json();# Python
import requests
import os
response = requests.post(
'https://api.htpbe.tech/v1/analyze',
headers={
'Authorization': f"Bearer {os.getenv('HTPBE_API_KEY')}",
'Content-Type': 'application/json'
},
json={
'url': 'https://example.com/documents/contract.pdf'
}
)
result = response.json()Analysis is performed synchronously. The response contains only the check ID. A Location response header points to the full result URL. Call GET /api/v1/result/{id} immediately after to retrieve the full analysis results.
| Header | Description |
|---|---|
Location |
Full URL of the result: https://api.htpbe.tech/v1/result/{id} (e.g. https://api.htpbe.tech/v1/result/3f9c8b7a-2e1d-4c5f-9b8e-7a6d5c4b3a21) |
{
id: string;
}- Type:
string(UUID v4) - Always Present: Yes
- Description: Unique identifier for this analysis check
- Format:
xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx(UUID version 4) - Usage: Pass this ID to
GET /api/v1/result/{id}to retrieve the full analysis - Example:
"3f9c8b7a-2e1d-4c5f-9b8e-7a6d5c4b3a21"
{
"id": "3f9c8b7a-2e1d-4c5f-9b8e-7a6d5c4b3a21"
}// Step 1: Submit PDF for analysis
const analyzeRes = await fetch('https://api.htpbe.tech/v1/analyze', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HTPBE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ url: 'https://example.com/documents/contract.pdf' }),
});
const { id } = await analyzeRes.json();
// Step 2: Retrieve full results
const resultRes = await fetch(`https://api.htpbe.tech/v1/result/${id}`, {
headers: { Authorization: `Bearer ${process.env.HTPBE_API_KEY}` },
});
const result = await resultRes.json();
// result.status: "intact" | "modified" | "inconclusive"
// ... (see /result endpoint docs for full schema)See GET /api/v1/result/{id} for the full result schema, including verdict fields (status, modification_confidence, modification_markers), metadata, structure, signatures, threats, and findings.
The verdict fields (status, modification_confidence, modification_markers) are available in the result endpoint. See GET /api/v1/result/{id} for details.
How status: "modified" is determined:
The verdict is set to "modified" when one or more forensic markers fire. Markers are returned in modification_markers[] as stable machine-readable ids (e.g. HTPBE_SIGNATURE_REMOVED, HTPBE_DATES_DISAGREE, HTPBE_MULTIPLE_REVISION_LAYERS, HTPBE_POST_SIGNATURE_EDIT). The full id → outcome-label dictionary is published on htpbe.tech/how — branch your integration logic on the id, render the user-facing label from the dictionary.
What we detect:
- Structural evidence of edits made after the document was created
- Contradictions in document metadata
- Digital signature removal or edits made after signing
- Traces left by editing software
What we don't detect:
- Document fabrication (entire content created in Word/Excel and exported to PDF)
- Content changes that leave no structural trace in the file
- Password-protected content
- Cryptographic signature validity
All errors follow this format:
{
"error": "Human-readable error message",
"code": "machine_readable_error_code",
"details": "Optional additional context (present for some errors)"
}Returned when the request is malformed or contains invalid parameters.
{
"error": "Invalid JSON body",
"code": "invalid_request"
}Cause: The request body is not valid JSON (missing braces, trailing commas, unquoted keys, etc.).
Solution: Ensure the request body is valid JSON and the Content-Type: application/json header is set.
{
"error": "Missing or invalid url parameter",
"code": "invalid_request"
}Cause: The url field is not present in the request body, or it's not a string.
Solution: Ensure you're sending a valid JSON body with a url string field.
{
"error": "Invalid url format",
"code": "invalid_url_format"
}Cause: The url value is not a valid HTTP or HTTPS URL.
Examples of Invalid URLs:
not-a-urlexample.com/file.pdf(missing protocol)file:///local/path.pdf(local path)https://user:password@example.com/file.pdf(embedded credentials — returned with"details": "URLs with embedded credentials are not supported.")
Note: ftp:// URLs are rejected with this error — they fail the HTTP/HTTPS protocol check before any download is attempted.
Solution: Use a complete HTTP or HTTPS URL like https://example.com/file.pdf
{
"error": "URL points to a private or reserved network",
"code": "invalid_url_format"
}Cause: The URL's host is, or resolves to, an address that is not publicly routable: loopback, private (RFC 1918), link-local and cloud metadata, carrier-grade NAT, multicast, documentation or other reserved ranges, in IPv4 or IPv6 form (including IPv4 addresses embedded in IPv6). The check applies to IP literals and to every address a hostname resolves to.
Solution: Host the file on a publicly reachable URL.
{
"error": "Failed to download file from URL",
"code": "download_failed",
"details": "Network error"
}details is one of a fixed set of values. It never contains text from the remote server's response or from the underlying network error:
details |
Meaning |
|---|---|
HTTP <status>: <reason> |
The URL answered with a non-2xx status, e.g. HTTP 404: Not Found. The reason is the standard phrase for that status code, not the text the server sent. |
HTTP <status> |
A non-2xx status with no standard reason phrase. |
HTTP <status>: redirects are not followed |
The URL answered with a 3xx redirect. Redirects are never followed — submit the final URL. |
Download timed out |
Downloading the file took longer than 30 seconds. |
Network error |
The host could not be reached or the connection failed during the download. |
Empty response body |
The URL answered 2xx with no content. |
Common Causes:
- URL returns 404 Not Found
- URL returns 403 Forbidden
- URL requires authentication
- URL redirects to another location
- Network timeout (30 second limit)
- DNS resolution failure
- Server is unreachable
HTTP Status Details Examples:
{
"error": "Failed to download file from URL",
"code": "download_failed",
"details": "HTTP 404: Not Found"
}{
"error": "Failed to download file from URL",
"code": "download_failed",
"details": "HTTP 403: Forbidden"
}Solution: Ensure the URL is publicly accessible and returns the file successfully.
Why 400 and not 422? This is intentional. HTTP 422 (Unprocessable Entity) means the request syntax is valid but the server cannot process the content. Here the problem is the client's input — the URL they supplied cannot be fetched. This is treated as a bad-input error (400), consistent with how invalid URL format is handled. Do not add 422 handling for this error code.
Authentication failed.
{
"error": "Missing API key. Please provide an API key in the Authorization header.",
"code": "missing_api_key"
}Cause: No Authorization header provided.
Solution: Add header: Authorization: Bearer YOUR_API_KEY
{
"error": "Invalid API key. Please check your credentials.",
"code": "invalid_api_key"
}Cause: Live key (htpbe_live_*) is missing, malformed, or not recognised. A key that exists but has been deactivated, or whose account has been disabled, returns 403 (inactive_client) instead.
Solution:
- Verify your API key is correct
- Generate a new API key from the dashboard if needed
{
"error": "Invalid test API key. Please check your credentials.",
"code": "invalid_api_key"
}Cause: Test key (htpbe_test_*) not found. Test keys are stored separately from live keys and cannot be used interchangeably.
Solution:
- Copy your test key from the Test API Key section on the dashboard
- Verify you are not using a live key where a test key is expected (or vice versa)
No credits remaining to run this check.
{
"error": "No credits remaining. Buy a credit pack or start a subscription to continue.",
"code": "payment_required"
}Cause: Your account has no credit source for this request — either a subscriber who has used the monthly quota and has no credit pack left, or a key with no credits and no active subscription. (Continued checking past the monthly quota is available only by individual agreement.)
Solution:
- Log in to your dashboard at https://htpbe.tech/dashboard
- Add a one-time credit pack, or subscribe to / upgrade a plan (Starter, Growth, or Pro)
- Your API access will resume immediately
Access forbidden due to account status.
{
"error": "This API key has been deactivated. Please contact support.",
"code": "inactive_client"
}Cause: The live key has been deactivated, or the account that owns the key (live or test) has been disabled.
Solution: Contact support to reactivate your account.
{
"error": "Test API keys can only be used with test URLs. See documentation for available test URLs.",
"code": "test_url_required",
"details": "Use URLs like: https://api.htpbe.tech/v1/test/clean.pdf, https://api.htpbe.tech/v1/test/modified-high.pdf, etc."
}Cause: A test API key (htpbe_test_...) was used with a real URL. Test keys are restricted to the predefined test URLs — they cannot download or analyze real PDFs.
Solution: Use one of the mock test URLs — see testing.md for the full list — or switch to a live API key (htpbe_live_...) to analyze real files.
{
"error": "This account cannot run checks. Contact support if this is a mistake.",
"code": "account_restricted"
}Cause: An account-level restriction applies. No restriction currently triggers this response, but the code is part of the contract and clients should keep handling it.
Solution: Contact support.
{
"error": "A request with this Idempotency-Key is already in progress for this account",
"code": "idempotency_key_in_progress",
"details": "Retry shortly. Do not change the idempotency key — that would spend credit twice."
}Cause: Another request using the same Idempotency-Key (see Idempotent Retries) is still being processed for your account.
The response includes a Retry-After header (in seconds, currently 2).
Solution: Wait for the Retry-After interval and retry with the same Idempotency-Key. Do not switch to a new key just to get past this error — that starts an independently-charged second request.
File exceeds size limit.
{
"error": "File size exceeds limit",
"code": "file_too_large",
"details": "Maximum file size is 10 MB, received 15 MB"
}Cause: PDF file is larger than 10 MB (10,485,760 bytes).
Solution:
- Compress the PDF using tools like Adobe Acrobat or online compressors
- Split large PDFs into smaller files
- Remove high-resolution images
- Contact support for Enterprise plan with higher limits
Request is valid but the content cannot be processed.
{
"error": "Invalid PDF file",
"code": "invalid_pdf",
"details": "The file could not be parsed as a PDF. It may be corrupt, truncated or not a PDF."
}details is a fixed string. It does not carry parser output, so it does not tell you where in the file parsing stopped.
An encrypted file returns its own variant:
{
"error": "PDF is encrypted and cannot be analyzed",
"code": "invalid_pdf",
"details": "Encrypted PDFs cannot be analyzed. Please provide an unencrypted document."
}Common Causes:
- File is not actually a PDF (wrong file type)
- PDF file is corrupted or truncated
- File is encrypted with a password
- PDF uses unsupported features
Solution:
- Verify the file opens correctly in a PDF reader
- Try re-saving the file
- Remove encryption/password protection
- If the file is valid, contact support with the file URL for investigation
{
"error": "PDF structure could not be read",
"code": "invalid_pdf",
"details": "The document structure could not be read. The file may be corrupt or truncated."
}Returned when the file parses far enough to be accepted as a PDF but its internal structure cannot be read. There is nothing in such a document to analyse, so no check is stored and no credit is consumed.
Same code (invalid_pdf) and same status as the other cases above, so no separate handling is needed. Note that this condition previously surfaced as a 500; it is a 4xx because the file, not the server, is at fault — do not retry it.
{
"error": "PDF could not be analyzed",
"code": "invalid_pdf",
"details": "Analysis was interrupted. The file may be malformed or too complex."
}Returned when the analysis worker is killed by the runtime — typically because the PDF is structurally pathological and would otherwise exhaust memory — or when a part of the analysis that every result depends on fails on our side. No check is stored, no id is returned and no credit or quota is used. The error code is the same as for malformed PDFs (invalid_pdf), so you do not need to handle it separately.
An analysis_incomplete result is not an error. It arrives as a successful 201 with a check id; the stored result you read with GET /result/{id} has status: "inconclusive", status_reason: "analysis_incomplete" (see result.md) and an empty modification_markers[]. It uses a credit or quota like any other delivered result. Treat that result as "not fully checked", not as clean. Reading it again with GET /result/{id}, or replaying the request with the same Idempotency-Key, costs nothing but returns this same result. Submitting the file again (with no key or a new one) runs a new analysis and may use another credit or quota — see Quota & Credits. Treat the document as unverified and ask the issuer for a fresh copy. If a modification was established even though the check could not be completed in full, the result is an ordinary modified one — markers included, no status_reason. If a fault on our side interrupts the analysis, there is no result at all, whatever it had found so far: the response is the Analysis Interrupted 422 below and nothing is stored or charged. The invalid_pdf responses documented here remain reserved for a file that cannot be analysed at all: malformed, encrypted or interrupted.
{
"error": "Analysis did not finish in time",
"code": "analysis_timeout",
"details": "The analysis ran out of time, so nothing was stored or charged. The server may be busy: try again in a minute."
}Returned when the analysis does not finish within its time limit. That says nothing about whether the file is valid: under load a request can run out of time while it waits for heavy work of an earlier request to finish, and a very large document can use the whole limit on its own. As with every 422 here, no check is stored, no id is returned and no credit or quota is used.
Solution: Unlike the other 422 codes, this one can succeed on retry. Wait a minute and retry once or twice with backoff — with the same Idempotency-Key if you sent one; a key whose attempt ended in this error starts a new attempt and spends nothing twice. If the same file keeps returning analysis_timeout when the server is otherwise idle, it is too heavy to analyse within the limit; contact support with the URL.
{
"error": "This Idempotency-Key was already used for a different url",
"code": "idempotency_key_fingerprint_mismatch",
"details": "Idempotency-Key values must be unique per logical request. Use a new key for a different document."
}Cause: The same Idempotency-Key was sent with a url different from the one it was first used with (see Idempotent Retries).
Solution: Generate a new key per document. Never reuse a key across two different documents — the server refuses the request rather than returning a stale verdict for the wrong file.
The request could not be admitted for analysis right now. Analyses run a limited number at a time; when every slot is busy, a request waits in a queue that all accounts share. The request is refused with 429 when that queue is full, when your account already holds its share of the queue, or when the wait runs out.
{
"error": "Server is at analysis capacity, retry shortly",
"code": "server_at_capacity",
"details": "Concurrent analyses in flight: 2 of 2."
}The response includes a Retry-After header (in seconds) indicating how long to wait before retrying.
Common Causes:
- A burst of parallel requests from your account — waiting requests are counted per account, across all of its API keys, so spreading a burst over several keys does not raise your share
- Many requests from other accounts at the same time
- A long-running analysis on a particularly complex PDF holding a slot
Solution:
- Respect the
Retry-Afterheader — wait the indicated number of seconds, then retry the same request - Use exponential backoff if you receive multiple 429s in a row
- If you need higher sustained throughput, contact support — Enterprise plans can be deployed with elevated concurrency limits
Note: This is analysis capacity, not a request-rate limit. Two limits apply: the server-wide number of analyses running and waiting, and each account's share of the waiting queue. Because of the second, your account can receive 429 while other accounts are still being served. It applies to live keys only: test-key requests return synthetic results without running an analysis, so they never receive this 429. Keep the same retry path in your client for both key types, so code tested with a test key behaves correctly once you switch to a live key.
Honour Retry-After when present, and fall back to exponential backoff (with a little jitter) otherwise. Retry on 429, 500, and 409 — a 409 means a request with the same Idempotency-Key is already in progress; wait and retry with the same key (see 409 Conflict). Other 4xx errors such as 400 or 422 will not succeed on retry — except 422 with code analysis_timeout, which may succeed once the server is less busy (see Analysis Timeout).
// Node.js / TypeScript
async function analyzeWithRetry(url, maxRetries = 5) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const response = await fetch('https://api.htpbe.tech/v1/analyze', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HTPBE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ url }),
});
if (![409, 429, 500].includes(response.status)) {
return response; // success or a non-retryable error
}
if (attempt === maxRetries) {
throw new Error(`Giving up after ${maxRetries} retries (last status ${response.status})`);
}
const retryAfter = Number(response.headers.get('Retry-After'));
const backoff =
Number.isFinite(retryAfter) && retryAfter > 0
? retryAfter * 1000
: Math.min(2 ** attempt * 1000, 30_000) + Math.random() * 1000;
await new Promise((resolve) => setTimeout(resolve, backoff));
}
}# Python
import os
import random
import time
import requests
def analyze_with_retry(url, max_retries=5):
for attempt in range(max_retries + 1):
response = requests.post(
'https://api.htpbe.tech/v1/analyze',
headers={
'Authorization': f"Bearer {os.getenv('HTPBE_API_KEY')}",
'Content-Type': 'application/json',
},
json={'url': url},
)
if response.status_code not in (409, 429, 500):
return response # success or a non-retryable error
if attempt == max_retries:
response.raise_for_status()
retry_after = response.headers.get('Retry-After')
if retry_after and retry_after.isdigit():
backoff = int(retry_after)
else:
backoff = min(2 ** attempt, 30) + random.random()
time.sleep(backoff)Server-side error during processing.
{
"error": "Failed to analyze PDF",
"code": "internal_error",
"request_id": "3f2a9c1e-5b7d-4e8a-9c0f-1d2e3b4a5c6d"
}request_id is the id of this request, also returned in the x-request-id header.
Cause: Unexpected server error. This is rare and usually indicates a bug.
Solution:
- Retry the request (may be a transient error)
- If persists, contact support with the
request_id - Check our status page for any ongoing incidents
Use test API keys (htpbe_test_...) to integrate without consuming quota or analyzing real PDFs. Test keys return deterministic UUID v4 check IDs (e.g., 00000000-0000-4000-8000-000000000001 for clean.pdf, 00000000-0000-4000-8000-000000000005 for modified-high.pdf) for the predefined mock URLs plus an error-trigger URL — no real file is downloaded and no quota is consumed.
See testing.md for the full list of test URLs, synthetic ID table, code examples, and checklist.
- Typical: 2-5 seconds for average PDFs (1-20 pages)
- Larger files: 5-15 seconds for complex PDFs (50-100 pages)
- Download timeout: 30 seconds. Requests where downloading the source URL exceeds this fail with
download_failed(400). - Analysis timeout: 20 seconds. An analysis that does not finish in time fails with
analysis_timeout(422) and is not charged. This is independent of the download timeout.
- ✅ PDF versions 1.0 through 2.0
- ✅ Linearized (Fast Web View) PDFs
- ✅ PDFs with forms, annotations, and multimedia
- ✅ Signed PDFs (detects but doesn't validate signatures)
- ❌ Cannot validate cryptographic signatures (only detects presence/removal)
- ❌ Password-protected PDFs — the password must be removed before submitting for analysis
- ❌ Cannot analyze files behind authentication
- ❌ Does not perform OCR or content analysis
- ❌ Does not detect visual changes (only structural/metadata changes)
Related Endpoints:
- GET /api/v1/result/{id} - Retrieve full analysis results
- GET /api/v1/checks - List all checks with filtering for custom analytics