Skip to main content

Proofread File API

This guide helps you easily integrate the Trinka Proofread File API into your applications to automatically edit an entire document and get a track-changed document as an output.

Use Cases

Here are some of the things that Proofread File API can do for you:

  • Find and fix grammar mistakes in an entire document
  • Process Word and LaTeX files
  • Return a language quality score for your documents
  • Recommend human editing services based on the language quality score

How to Get Started

  1. Get an API key - You'll need an API key to identify your account and track usage. Generate a test key for development or a production key for live use by visiting https://developer.trinka.ai/landing/apikeys

  2. Send an API request - Send an HTTPs request to Trinka for checking your document. Note that the API uses RESTful architecture, and the input/output is in JSON format. Standard HTTP response codes, authentication, and verbs are used. The content-type of both request and response must be application/json.

  3. Get the results - You will be able to download the edited file as well as get statistics about the edited document, such as the language quality score and the number of alerts in each grammar category.

  4. Handle errors - Trinka uses standard codes to indicate success or problems. Refer to the appendix for more details.

API Request-Response

Please follow the given steps to upload and process a document.

Request: https://api-platform.trinka.ai/autoedit/v3/document/create

Curl:

curl --location --request POST 'https://api-platform.trinka.ai/autoedit/v3/document/create' \
--header 'x-api-key: <<<<your x-api-key>>'
Response: {
"status": true,
"message": "success",
"data": "https://b2bapi.trinka.ai/autoedit/v2/submission/<<uuid>>",
"service_type": null
}

In the response of the Create Token API, the data field contains a unique document upload url valid for 30 seconds. You need to use this url in the upload document API described below.

Step 2: Upload a Document (Submit File API):

Request: https://b2bapi.trinka.ai/autoedit/v2/submission/<uuid>;

Curl:

curl --location --request POST 'https://b2bapi.trinka.ai/autoedit/v2/submission/<uuid>' \
--header 'x-api-key: <<your x-api key>>' \
--form 'statistics_in_document="false"' \
--form 'revisions_as_tracks="true"' \
--form 'revisions_as_comments="false"' \
--form 'file="' \
--form 'pipeline="eagles"' \
--form 'language="US"' \
--form 'enhancement="false"' \
--form 'writing_advisor="false"' \
--form 'grammar="true"' \
--form 'spellings="true"'

Input Parameters for the Submit File API

Parametertypemandatory/optionalValuesNotes
filefilemandatoryvariousSelect a doc/docx file
languagestringoptionalUS, UKChoose between American English (US) or British English (UK). Default is American English (US).
pipelinestringoptionalpanini1, eagles, panini2Choose eagles for making only corrections, panini2 for extensive paraphrase-like changes, and panini1 for moderately extensive changes. The default is panini1.
grammarbooleanoptionaltrue, falseChoose whether to insert grammar alerts. Default: true
spellingsbooleanoptionaltrue, falseChoose whether to insert spellings alerts. Default: true
enhancementbooleanoptionaltrue, falseChoose whether to insert enhancement alerts. Default: false
writing_advisorbooleanoptionaltrue, falseChoose whether to insert writing advisor alerts. Default: false
statistics_in_documentbooleanoptionaltrue, falseInclude back cover with statistics around the different revisions made in the document along with document score. Default is false.
authorstringoptionalvariousAnnotation name for track changes. Default is ‘Trinka’.
style_guidestringoptionalAPA, ACS, AMA, IEEE, AGUStyle guide options for retail customers. Please contact our sales team for details on how to get your style guide added as an option.
revisions_as_tracksbooleanoptionaltrue, falseApply revisions in the document and make it available in track changes. Default is true.
revisions_as_commentsbooleanoptionaltrue, falseApply revisions in the document as comments. Default is false.

Response of the Submit File API

Response:{
"status":true,
"message":"success", "data":
{
"id":"<uuid>",
"filename":"<somefile>",
"status":"<status>",
"message":"<message>",
"credits":<credit deduction>,
"words":<file word count>,
"error_report":null,
"language":"<language options>",
"statistics_in_document":true/false,
"writing_advisor_as_comment":true/false,
"revision_as_tracks":true/false,
"revision_as_comment":true/false,
"created_on":<epoch time>,
"modified_on":<epoch time>
}
}

Parameters of the Response of the Submit File API

Parametertypemandatory/optionalValuesNotes
iduuidmandatoryvariousUnique document id generated at the time of document submission
filenamestringmandatoryvariousName of the submitted file
statusstringmandatoryWAITING_IN_QUEUE,
IN_PROGRESS,
SUCCESS, FAILED
WAITING_IN_QUEUE: added to queue IN_PROGRESS: under processing SUCCESS: File processed successfully FAILED: Failed to process the file
messagestringoptionalVariousDetails of status as required. For example, Word limit per file restriction, File corrupted, etc.
wordsintegermandatoryVariousThe total number of words detected in the submitted document.
error_reportobjectoptionalVariousNote: Ignore on document submission
languagestringmandatoryUS, UKThe user selected option at the time of upload: American English (US) or British English (UK).
statistics_in_documentbooleanoptionaltrue, falseInclude back cover with statistics around the different revisions made in the document along with document score. Default is true.
revisions_as_tracksbooleanoptionaltrue, falseApply revisions in the document and make it available in track changes. Default is true.
revisions_as_commentsbooleanoptionaltrue, falseApply revisions in the document as comments. Default is false.
writing_advisor_as_commentsbooleanoptionaltrue, falseInclude non-cta enhancements and writing advisor revisions in the form of comments in the document. Default is true.

Step 3: Get Document Status (Document Status API)

Request: https://api-platform.trinka.ai/autoedit/v3/document/<uuid>

Curl:

curl --location 'https://api-platform.trinka.ai/autoedit/v3/document/<uuid>' \
--header 'x-api-key: <<your x-api-key>>'

Input Parameters for the Document Status API

  1. document_id: This is a unique document id received at the time of document submission.

Response of the Document Status API

{
"status": true,
"message": "success",
"data": {
"id": "<<document id>>",
"filename": "<<filename>>",
"status": "SUCCESS",
"message": null,
"credits": 1,
"words": 610,
"language": "US",
"parentExtension": "docx",
"deleted": false,
"error_id": -1,
"error_report": {
"style_guide": 0,
"pronoun_and_determiner": 0,
"complexity": 0,
"other": 19,
"symbols_notations": 0,
"redundancy_conciseness": 0,
"enhancement": 0,
"conjunction": 0,
"word_choice": 0,
"preposition": 0,
"writing_advisor": 0,
"capitalization_and_spacing": 0,
"word_form": 0,
"abbreviations": 0,
"sva": 0,
"plain_language": 0,
"spelling": 0,
"verb": 1,
"noun": 0,
"word_order": 0,
"number_style": 0,
"article": 2,
"fragment": 0,
"adverb_and_adjective": 0,
"punctuation": 1,
"idioms": 0,
"syntax": 0,
"style": 1,
"sensitive_language": 0,
"tense": 0,
"run_on": 0,
"categories": {
"R:OTHER": 1,
"M:VERB": 1,
"Subject-verb agreement": 3,
"M:PUNCT": 1,
"R:CONTR": 1,
"M:OTHER": 1,
"Syntax": 1,
"English Style-US": 12,
"M:PUNCT R:ORTH": 1,
"M:DET": 2
},
"ce_label": -1,
"language_score": 69,
"total_corrections": 24,
"total_suggestions": 0,
"total_sentences": 42
},
"statistics_in_document": false,
"writing_advisor_as_comments": true,
"revisions_as_tracks": true,
"revisions_as_comments": false,
"inclusive_lang": false,
"created_on": 1721899089841,
"modified_on": 1721899091525,
"style_guide": "NONE",
"process_start_time": 1721899089910,
"process_end_time": 1721899090682,
"word_count": 610,
"word_limit": 0,
"readonly": false
},
"service_type": null
}

Parameters of Response of the Document Status API

Parametertypemandatory/optionalValuesNotes
iduuidmandatoryvariousUnique document id generated at the time of document submission
filenamestringmandatoryvariousName of the submitted file
statusstringmandatoryWAITING_IN_QUEUE,
IN_PROGRESS,
SUCCESS,FAILED
WAITING_IN_QUEUE: added to queue IN_PROGRESS: under processing SUCCESS: File processed successfully FAILED: Failed to process the file
messagestringoptionalVariousDetails of status as required. For example, Word limit per file restriction, File corrupted, etc.
wordsintegermandatoryVariousThe total number of words detected in the submitted document.
error_idintegeroptionalVariousIn case the document status is FAILED error_id field will provide the error number.
error_reportobjectmandatoryVariousDistribution of errors under various error categories
language_scorenumbermandatoryVariousA number between 0 and 100 that denotes the language quality score.
total_correctionsintegermandatoryVariousTotal number of corrections suggested for the document
total_suggestionsintegermandatoryVariousTotal number of suggestion comments added in the document
total_sentencesintegermandatoryVariousTotal number of sentences in the document
statistics_in_documentbooleanoptionaltrue, falseInclude back cover with statistics around the different revisions made in the document along with document score. Default is true.
revisions_as_tracksbooleanoptionaltrue, falseApply revisions in the document and make it available in track changes. Default is true.
revisions_as_commentsbooleanoptionaltrue, falseApply revisions in the document as comments. Default is false.
writing_advisor_as_commentsbooleanoptionaltrue, falseInclude non-cta enhancements and writing advisor revisions in the form of comments in the document. Default is true.

Step 4: Download Processed File

Request URL: https://api-platform.trinka.ai/autoedit/v3/document/<<document id>>/final

Curl:


curl --location 'https://api-platform.trinka.ai/autoedit/v3/document/<<document id>>/final' \
--header 'x-api-key: <<your x-api key>>'

Input Parameters for the Download File API

  1. document_id: This is a unique document id received at the time of document submission.

Response of the Download File API

{
"status": true,
"message": "success",
"data": "https://autoedit.trinka.ai/download/6eb98551-8a00-4848-8d9d-d80c30e53c5b",
"service_type": null
}

In the response of the Download File API, the data field contains the URL for downloading the processed file. If you upload a docx file, the processed file will be a docx file containing Track Changes. If you upload a LaTeX file, the processed file will be a zip file containing a docx file with Track Changes as well as a LaTeX file with all changes already applied in it.

API Limits

  1. Proofread File API can currently accept 2 requests/second when called using the Production API Key and 1 request/second when called using the Test API Key.
  2. Proofread File API can currently process a maximum of 100,000 words in each request.

Trinka API Response Codes

200 - OKEverything worked as expected.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter or file format not acceptable.
401 - UnauthorizedNo valid API key provided.
403 - ForbiddenThe API key doesn't have permissions to perform the request.
429 - Too Many RequestsThe API rate limit is exceeded.
404 - Not FoundThe requested resource doesn't exist.
500 - Server errorTrinka server issue