Guides

Checking a file

/v1/check answers one question — will this file open cleanly in Office? — and tells you exactly what a repair would change, without changing anything.

Sending the file

Upload the file as multipart/form-data in a field named file, up to 50 MB. The filename's extension — .xlsx, .docx or .pptx — says which format to expect; anything else is 415 unsupported_file_type.

curl https://api.ihatecorruptfiles.xyz/v1/check \
  -H "Authorization: Bearer $IHCF_API_KEY" \
  -F file=@report.xlsx

The verdict

verdict sums the file up in one of six words. It is the field to branch on; opens_in_office and repairable say the same thing another way.

verdict	Means	Do
ok	Valid, and Office opens it. Nothing to do.	Ship it.
tolerated	Breaks the standard in a way Office accepts. Left alone.	Ship it.
unconfirmed	Breaks the standard; this case has not been checked against Office.	Ship it, or repair to be safe.
needs_repair	Opens, but something inside is wrong — a total, a type, a link. Repairable.	Repair it.
broken	Office refuses it or shows its repair prompt.	Repair it.
unsupported	Encrypted, a renamed pre-2007 file, or empty. See reason.	Tell the user; see reason.

Findings and actions

findings is what is wrong with the file as you sent it — each with a severity of blocks, tolerated or unconfirmed, the part, and where in it. actions is every change a repair would make, in the order it would make them. Actions marked advisory are only reported: a narrow column, a function older Excel lacks, a total we can't prove wrong.

A file can need a repair with no findings at all: the example above passes the standard, but a number stored as text breaks its SUM. That is a semantics action. The reference lists every field.

Deciding in code

Python

result = response.json()
verdict = result["verdict"]

if verdict in ("ok", "tolerated"):
    ship(path)
elif result["repairable"]:
    repair(path)              # POST /v1/repair
elif verdict == "unconfirmed":
    ship(path)                # not known to break Office
else:
    raise ValueError(result["reason"] or verdict)

Calling /v1/check first costs a request. If you will repair anything that needs it anyway, call /v1/repair directly: a file that needs nothing comes back unchanged.