This reference is generated from the API's OpenAPI 3.1 document, available at https://api.fileverity.com/v1/openapi.json, so it always matches the API. For concepts and guides, start with the Overview.
Base URL: https://api.fileverity.com/v1. Authenticate every request with Authorization: Bearer <key>. Errors share one format, described in Errors. Every response carries an x-request-id header, and authenticated responses carry the rate-limit headers described in Rate limits and headers. Nested objects open in collapsible sections under the table.
Classifies plain text as AI-written, partly AI-written or human-written and returns the AI-written passages. The text is evaluated and discarded; it is not stored. Billing counts Unicode code points in units of 1,000 characters, rounded up per request. Requests rejected before evaluation are not charged. Test keys return a fixed human result without charge.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
No
Unique key of up to 255 characters. Repeating the request with the same key and body within 24 hours returns the first response with the header idempotent-replayed: true; the same key with a different body returns 409.
Request body: application/json, required
Field
Type
Required
Description
model
string
No
Model ID or snapshot ID. Default "fvdoc-3-text".
text
string
Yes
Plain text, at least 100 words and at most 100,000 characters.
language
one of "en", "fr", "de", "es", "zh", null
No
ISO 639-1 code. Detected automatically when omitted. Default null.
Uploads a file for analysis. Send files up to 4 MB as multipart/form-data in the field file; the response has status uploaded. Files larger than 4 MB must be uploaded with a pre-signed URL. Send JSON with filename, content_type and bytes (documents up to 50 MB); the response has status pending and an upload object with a pre-signed URL: send the file bytes to it with PUT and the given headers before it expires. A file is deleted when an analysis starts and at the latest after 24 hours. A workspace can hold up to 50 unexpired files and 200 MB per mode at once.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
No
Unique key of up to 255 characters. Repeating the request with the same key and body within 24 hours returns the first response with the header idempotent-replayed: true; the same key with a different body returns 409.
Request body: multipart/form-data, required
Field
Type
Required
Description
file
string
Yes
Format binary.
Request body: application/json, required
Field
Type
Required
Description
filename
string
No
content_type
string
Yes
MIME type of the file, for example image/jpeg or application/pdf.
bytes
integer
Yes
Exact size in bytes. Minimum 1. Maximum 52,428,800.
Analyzes an uploaded file with fvimg-2 (images) or fvdoc-3 (documents). An analysis is one image or document check. The response is 202 with status processing; the result arrives by webhook or by polling GET /analyses/{id}. Send Prefer: wait=N (up to 60 seconds) to hold the request until the result is ready; a finished analysis returns 200. The price is reserved when the analysis is created and released if it fails or is canceled. Results are kept for 7 days. When capacity is busy the API returns 503 service_unavailable with a retry-after header and charges nothing: retry with the same Idempotency-Key, and run image analyses one after another for the best throughput. Test keys return a sample result and are never charged; the sample report contains only a few fields.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
No
Unique key of up to 255 characters. Repeating the request with the same key and body within 24 hours returns the first response with the header idempotent-replayed: true; the same key with a different body returns 409.
Prefer
header
string
No
wait=N holds the request for up to N seconds (maximum 60) until the analysis finishes.
Request body: application/json, required
Field
Type
Required
Description
model
one of "fvimg-2", "fvimg-2-2026-10-30", "fvdoc-3", "fvdoc-3-2026-11-03"
Yes
Model ID or snapshot ID. fvimg-2 analyzes images, fvdoc-3 documents.
file
string
Yes
ID of an uploaded file.
metadata
object of string
No
Up to 16 string pairs (keys up to 40 characters, values up to 500) returned on the analysis and in webhooks.
options
object
No
options: fields
Field
Type
Required
Description
password
string
No
Password of an encrypted document. Maximum length 256.
Missing or invalid API key. Error codes: missing_api_key, invalid_api_key.
Error
402
The balance or the key's monthly spend limit cannot cover the request. Error codes: insufficient_balance, spend_limit_reached.
Error
404
Resource not found. Error codes: model_not_found.
Error
409
Conflict with the current state. Error codes: idempotency_mismatch, idempotency_in_progress.
Error
413
A size limit was exceeded. Error codes: file_too_large, too_many_pixels, too_many_pages, document_too_long.
Error
415
Unsupported media type or file format. Error codes: unsupported_media_type, unsupported_file.
Error
422
The file cannot be processed. Error codes: invalid_file, password_required, wrong_password, not_examinable.
Error
429
Too many requests. Error codes: rate_limited.
Error
500
Internal error; not charged. Error codes: internal_error.
Error
502
Analysis could not be completed; not charged. Error codes: analysis_failed.
Error
503
Temporarily unavailable or busy; not charged. Retry after the number of seconds in the retry-after header. Error codes: service_unavailable.
Error
Response 200: Analysis
Field
Type
Required
Description
id
string
Yes
object
"analysis"
Yes
created
integer
Yes
Unix timestamp.
model
string
Yes
Snapshot that produced the result.
livemode
boolean
Yes
status
one of "processing", "succeeded", "failed", "canceled"
Yes
file
object
Yes
report_id
string or null
Yes
Verifiable report ID, FV-XXXX-XXXX-XXXX.
report_url
string or null
Yes
Public verification page of the report.
summary
ImageSummary or DocumentSummary or null
Yes
The short, stable verdict: an ImageSummary for images, a DocumentSummary for documents, null until the analysis succeeds.
result
object or null
Yes
Present once status is succeeded and until the result expires.
error
object or null
Yes
progress
object or null
Yes
usage
object
Yes
metadata
object or null
Yes
completed_at
integer or null
Yes
expires_at
integer or null
Yes
Unix timestamp after which the result is deleted.
file: fields
Field
Type
Required
Description
name
string or null
No
bytes
integer or null
No
format
string or null
No
summary (ImageSummary): fields
Field
Type
Required
Description
level
one of "L0", "L1", "L2", "L3", "L4", "L5"
Yes
Risk level, L0 to L5.
assessment
one of "authentic_untouched", "authentic_locally_edited", "ai_generated", "undetermined"
Yes
action
one of "accept", "review", "reject", "resubmit"
Yes
ai
one of "labelled", "very_likely", "suspected", "undecided", "low", "very_low", "not_evaluated"
Yes
The finding on AI generation.
edit
one of "detected", "suspected", "suspected_record", "review", "generative", "minor", "none", "not_applicable", "not_evaluated"
Yes
The finding on local editing.
summary (DocumentSummary): fields
Field
Type
Required
Description
kind
"docpro"
Yes
level
one of "L0", "L1", "L2", "L3", "L4", "L5"
Yes
Risk level, L0 to L5.
action
one of "accept", "note", "review", "reject", "resubmit"
Yes
note: check the AI content marked in the report against your policy.
reason
string or null
Yes
The finding or condition behind the level, for example clean or incomplete, or a finding ID.
findings
array of string
Yes
IDs of the findings that matter.
pages
integer
Yes
Pages in the document.
images
integer
Yes
Embedded photos examined.
text
one of "ai_generated", "mixed", "human", "inconclusive", null
Yes
The verdict on the document's text, or null when text was not evaluated.
strong
true
No
Present when a listed finding is strong.
result: fields
Field
Type
Required
Description
report
ImageReport or DocumentReport
No
The full report. report.schema is fileverity.report/1 for images and fileverity.docpro/1 for documents.
stamped_at
integer or null
No
Unix timestamp of the RFC 3161 timestamp issued for the report, or null.
report (ImageReport): fields
Field
Type
Required
Description
schema
"fileverity.report/1"
Yes
id
string
Yes
Report ID, FV-XXXX-XXXX-XXXX.
sample
true
No
Present on the fixed sample reports that test keys return.
issuedAt
string
No
When the report was issued, ISO 8601 in UTC. Format date-time.
issuer
object
No
Who issued the report.
file
object
No
The checked image.
pro
object
No
The verdict. The same values as summary, with reason.
score
integer or null
No
Authenticity score from 0 to 100 in steps of 5: how strongly the evidence supports the image as an authentic, unedited capture. null when not evaluated.
confidence
one of "high", "medium", "low"
No
How much this file allows the analysis to establish. Low confidence usually reflects the file itself, such as low resolution or heavy compression.
questions
object
No
The three questions the report answers.
generator
object or null
No
The AI generator named for the image, or null.
regions
array of object
No
Flagged regions, in pixels of the displayed image.
provenance
object
No
What the file's own records say about its origin.
digest
string
No
Fingerprint of the report content, used by the verification page.
issuer: fields
Field
Type
Required
Description
name
string
No
operator
string
No
verify
string
No
Public verification page of the report.
file: fields
Field
Type
Required
Description
name
string or null
No
sha256
string
No
SHA-256 of the checked file, in hex.
bytes
integer
No
width
integer
No
Width in pixels as displayed.
height
integer
No
Height in pixels as displayed.
format
string
No
pro: fields
Field
Type
Required
Description
level
one of "L0", "L1", "L2", "L3", "L4", "L5"
No
Risk level, L0 to L5.
action
one of "accept", "review", "reject", "resubmit"
No
assessment
one of "authentic_untouched", "authentic_locally_edited", "ai_generated", "undetermined"
No
reason
string or null
No
questions: fields
Field
Type
Required
Description
ai
object
No
edit
object
No
source
object
No
ai: fields
Field
Type
Required
Description
key
one of "labelled", "very_likely", "suspected", "undecided", "low", "very_low", "not_evaluated"
No
basis
one of "verified", "detected", "declared", null
No
What the answer rests on.
strength
one of "strong", "moderate", "limited", null
No
How strongly the evidence supports the answer.
likelihood
integer or null
No
Likelihood of AI generation from 0 to 100 in steps of 5, or null.
edit: fields
Field
Type
Required
Description
key
one of "detected", "suspected", "suspected_record", "review", "generative", "minor", "none", "not_applicable", "not_evaluated"
No
basis
one of "verified", "detected", "declared", null
No
What the answer rests on.
strength
one of "strong", "moderate", "limited", null
No
How strongly the evidence supports the answer.
regions
integer
No
Number of flagged regions.
source: fields
Field
Type
Required
Description
key
string
No
basis
one of "verified", "detected", "declared", null
No
What the answer rests on.
strength
one of "strong", "moderate", "limited", null
No
How strongly the evidence supports the answer.
signer
string or null
No
aiClaim
boolean
No
Whether the file's own records claim AI generation.
generator: fields
Field
Type
Required
Description
name
string
No
basis
string
No
How the generator was identified.
regions: fields
Field
Type
Required
Description
id
string
No
x
integer
No
y
integer
No
w
integer
No
h
integer
No
strength
one of "high", "medium"
No
provenance: fields
Field
Type
Required
Description
credentials
one of "valid", "unverified", "issues", "invalid", "removed", "none"
No
State of the Content Credentials.
signer
string or null
No
software
array of string
No
Software named in the file's records.
camera
string or null
No
captured
string or null
No
Capture time recorded in the file, if any.
report (DocumentReport): fields
Field
Type
Required
Description
schema
"fileverity.docpro/1"
Yes
id
string
Yes
Report ID, FV-XXXX-XXXX-XXXX.
sample
true
No
Present on the fixed sample reports that test keys return.
issuedAt
string
No
When the report was issued, ISO 8601 in UTC. Format date-time.
receivedAt
string
No
When the file was received, ISO 8601 in UTC. Format date-time.
issuer
object
No
Who issued the report.
file
object
No
The checked document.
level
one of "L0", "L1", "L2", "L3", "L4", "L5"
No
Risk level, L0 to L5.
action
one of "accept", "note", "review", "reject", "resubmit"
No
reason
string or null
No
The finding or condition behind the level.
findings
array of object
No
The findings behind the level, each with the pages and embedded photos it refers to.
text
object
No
The result for the document's text.
images
array of object
No
The embedded photos and graphics, numbered in document order.
structure
object or null
No
The edit history of the file, or null when it was not examined.
provenance
object
No
What the file's own records say about its origin.
digest
string
No
Fingerprint of the report content, used by the verification page.
issuer: fields
Field
Type
Required
Description
name
string
No
operator
string
No
verify
string
No
Public verification page of the report.
file: fields
Field
Type
Required
Description
name
string or null
No
sha256
string
No
SHA-256 of the checked file, in hex.
bytes
integer
No
format
string
No
pages
integer
No
textLayer
one of "present", "partial", "absent"
No
Whether the document carries a text layer.
findings: fields
Field
Type
Required
Description
id
string
No
basis
one of "verified", "detected", "declared"
No
strength
one of "strong", "moderate", "limited"
No
material
boolean
No
Whether the finding counts toward the level.
pages
array of integer
No
images
array of integer
No
text: fields
Field
Type
Required
Description
status
one of "evaluated", "insufficient_text", "unsupported_language", "no_text"
No
verdict
one of "ai_generated", "mixed", "human", "inconclusive"
No
Present when status is evaluated.
words
integer
No
languages
array of string
No
passages
integer
No
Number of marked passages.
images: fields
Field
Type
Required
Description
n
integer
No
pages
array of integer
No
kind
one of "photo", "graphic"
No
width
integer
No
height
integer
No
level
one of "L0", "L1", "L2", "L3", "L4", "L5", null
No
assessment
one of "authentic_untouched", "authentic_locally_edited", "ai_generated", "undetermined", null
No
ai
one of "labelled", "very_likely", "suspected", "undecided", "low", "very_low", "not_evaluated", null
No
edit
one of "detected", "suspected", "suspected_record", "review", "generative", "minor", "none", "not_applicable", "not_evaluated", null
No
structure: fields
Field
Type
Required
Description
revisions
integer or null
No
changedPages
array of integer
No
addedPages
integer
No
signatures
integer
No
provenance: fields
Field
Type
Required
Description
credentials
string
No
State of the Content Credentials.
signer
string or null
No
aiClaim
boolean
No
Whether the file's own records claim AI generation.
Cancels a document analysis that is still processing and releases its charge. Image analyses cannot be canceled once created.
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
Analysis ID.
Idempotency-Key
header
string
No
Unique key of up to 255 characters. Repeating the request with the same key and body within 24 hours returns the first response with the header idempotent-replayed: true; the same key with a different body returns 409.
Responses
Status
Description
Body
200
The canceled analysis.
Analysis
400
Invalid request. Error codes: invalid_parameter.
Error
401
Missing or invalid API key. Error codes: missing_api_key, invalid_api_key.
Error
404
Resource not found. Error codes: not_found.
Error
409
Conflict with the current state. Error codes: not_cancelable, idempotency_mismatch, idempotency_in_progress.
Error
429
Too many requests. Error codes: rate_limited.
Error
500
Internal error; not charged. Error codes: internal_error.
Error
Response 200: Analysis
Field
Type
Required
Description
id
string
Yes
object
"analysis"
Yes
created
integer
Yes
Unix timestamp.
model
string
Yes
Snapshot that produced the result.
livemode
boolean
Yes
status
one of "processing", "succeeded", "failed", "canceled"
Yes
file
object
Yes
report_id
string or null
Yes
Verifiable report ID, FV-XXXX-XXXX-XXXX.
report_url
string or null
Yes
Public verification page of the report.
summary
ImageSummary or DocumentSummary or null
Yes
The short, stable verdict: an ImageSummary for images, a DocumentSummary for documents, null until the analysis succeeds.
result
object or null
Yes
Present once status is succeeded and until the result expires.
error
object or null
Yes
progress
object or null
Yes
usage
object
Yes
metadata
object or null
Yes
completed_at
integer or null
Yes
expires_at
integer or null
Yes
Unix timestamp after which the result is deleted.
file: fields
Field
Type
Required
Description
name
string or null
No
bytes
integer or null
No
format
string or null
No
result: fields
Field
Type
Required
Description
report
ImageReport or DocumentReport
No
The full report. report.schema is fileverity.report/1 for images and fileverity.docpro/1 for documents.
stamped_at
integer or null
No
Unix timestamp of the RFC 3161 timestamp issued for the report, or null.
Returns the sealed PDF report of a succeeded analysis while its result is kept. Test keys get 404. Document evidence such as page images is available for 3 hours after the analysis; after that the PDF omits it, signaled by x-evidence-included: false.
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
Analysis ID.
locale
query
one of "en", "fr", "de", "es", "zh", "vi", "ar"
No
Default "en".
Responses
Status
Description
Body
200
The PDF report.
PDF file
400
Invalid request. Error codes: invalid_parameter.
Error
401
Missing or invalid API key. Error codes: missing_api_key, invalid_api_key.
Error
404
Resource not found. Error codes: not_found.
Error
429
Too many requests. Error codes: rate_limited.
Error
500
Internal error; not charged. Error codes: internal_error.
{"object":"list","data":[{"id":"fvimg-2","object":"model","created": 1793318400,"owned_by":"fileverity","name":"FVIMG V2","type":"image","description":"Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.","snapshot":"fvimg-2-2026-10-30","status":"available","input":{"formats":["jpeg","png","webp"],"max_bytes": 10485760,"max_megapixels": 40},"output":{"schema":"fileverity.report/1"},"pricing":{"currency":"usd","unit":"image","unit_amount": 199}},{"id":"fvdoc-3","object":"model","created": 1793664000,"owned_by":"fileverity","name":"FVDOC V3","type":"document","description":"Document fraud analysis. Evaluates AI-written text, embedded photos, edit history and signatures, and returns a verifiable report.","snapshot":"fvdoc-3-2026-11-03","status":"available","input":{"formats":["pdf","docx","doc","rtf","odt","pptx","txt"],"max_bytes": 52428800,"max_pages": 100},"output":{"schema":"fileverity.docpro/1"},"pricing":{"currency":"usd","unit":"document","unit_amount": 599}},{"id":"fvdoc-3-text","object":"model","created": 1793664000,"owned_by":"fileverity","name":"FVDOC V3 Text","type":"text","description":"AI-written text detection. Classifies plain text as AI-written, partly AI-written or human-written and marks the AI-written passages.","snapshot":"fvdoc-3-text-2026-11-03","status":"available","input":{"languages":["en","fr","de","es","zh"],"min_words": 100,"max_characters": 100000},"output":{"schema":"fileverity.text-detection/1"},"pricing":{"currency":"usd","unit":"1000_characters","unit_amount": 14}}]}
{"id":"fvimg-2","object":"model","created": 1793318400,"owned_by":"fileverity","name":"FVIMG V2","type":"image","description":"Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.","snapshot":"fvimg-2-2026-10-30","status":"available","input":{"formats":["jpeg","png","webp"],"max_bytes": 10485760,"max_megapixels": 40},"output":{"schema":"fileverity.report/1"},"pricing":{"currency":"usd","unit":"image","unit_amount": 199}}
Delivered to your webhook endpoints following the Standard Webhooks specification: the headers webhook-id, webhook-timestamp and webhook-signature (v1,<base64 HMAC-SHA256 of id.timestamp.body>, keyed with the base64 part of your whsec_ secret). Respond with any 2xx within 10 seconds; failures are retried with exponential backoff for 3 days.
Request body: application/json, required
Field
Type
Required
Description
id
string
Yes
Also sent as the webhook-id header; use it to deduplicate retries.
object
"event"
Yes
type
one of "analysis.completed", "analysis.failed", "balance.low"
Yes
created
integer
Yes
Unix timestamp.
data
Analysis or BalanceLow
Yes
analysis.* events carry the same object as GET /analyses/{id}, with result always null; fetch the result with that endpoint. balance.low events carry the balance and threshold in cents.
Delivered to your webhook endpoints following the Standard Webhooks specification: the headers webhook-id, webhook-timestamp and webhook-signature (v1,<base64 HMAC-SHA256 of id.timestamp.body>, keyed with the base64 part of your whsec_ secret). Respond with any 2xx within 10 seconds; failures are retried with exponential backoff for 3 days.
Request body: application/json, required
Field
Type
Required
Description
id
string
Yes
Also sent as the webhook-id header; use it to deduplicate retries.
object
"event"
Yes
type
one of "analysis.completed", "analysis.failed", "balance.low"
Yes
created
integer
Yes
Unix timestamp.
data
Analysis or BalanceLow
Yes
analysis.* events carry the same object as GET /analyses/{id}, with result always null; fetch the result with that endpoint. balance.low events carry the balance and threshold in cents.
Delivered to your webhook endpoints following the Standard Webhooks specification: the headers webhook-id, webhook-timestamp and webhook-signature (v1,<base64 HMAC-SHA256 of id.timestamp.body>, keyed with the base64 part of your whsec_ secret). Respond with any 2xx within 10 seconds; failures are retried with exponential backoff for 3 days.
Request body: application/json, required
Field
Type
Required
Description
id
string
Yes
Also sent as the webhook-id header; use it to deduplicate retries.
object
"event"
Yes
type
one of "analysis.completed", "analysis.failed", "balance.low"
Yes
created
integer
Yes
Unix timestamp.
data
Analysis or BalanceLow
Yes
analysis.* events carry the same object as GET /analyses/{id}, with result always null; fetch the result with that endpoint. balance.low events carry the balance and threshold in cents.