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
-
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
-
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.
-
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.
-
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.
Step 1: Generate a Document Submission Link (Create Token API)
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
Parameter | type | mandatory/optional | Values | Notes |
---|---|---|---|---|
file | file | mandatory | various | Select a doc/docx file |
language | string | optional | US, UK | Choose between American English (US) or British English (UK). Default is American English (US). |
pipeline | string | optional | panini1, eagles, panini2 | Choose eagles for making only corrections, panini2 for extensive paraphrase-like changes, and panini1 for moderately extensive changes. The default is panini1. |
grammar | boolean | optional | true, false | Choose whether to insert grammar alerts. Default: true |
spellings | boolean | optional | true, false | Choose whether to insert spellings alerts. Default: true |
enhancement | boolean | optional | true, false | Choose whether to insert enhancement alerts. Default: false |
writing_advisor | boolean | optional | true, false | Choose whether to insert writing advisor alerts. Default: false |
statistics_in_document | boolean | optional | true, false | Include back cover with statistics around the different revisions made in the document along with document score. Default is false. |
author | string | optional | various | Annotation name for track changes. Default is ‘Trinka’. |
style_guide | string | optional | APA, ACS, AMA, IEEE, AGU | Style 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_tracks | boolean | optional | true, false | Apply revisions in the document and make it available in track changes. Default is true. |
revisions_as_comments | boolean | optional | true, false | Apply 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
Parameter | type | mandatory/optional | Values | Notes |
---|---|---|---|---|
id | uuid | mandatory | various | Unique document id generated at the time of document submission |
filename | string | mandatory | various | Name of the submitted file |
status | string | mandatory | WAITING_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 |
message | string | optional | Various | Details of status as required. For example, Word limit per file restriction, File corrupted, etc. |
words | integer | mandatory | Various | The total number of words detected in the submitted document. |
error_report | object | optional | Various | Note: Ignore on document submission |
language | string | mandatory | US, UK | The user selected option at the time of upload: American English (US) or British English (UK). |
statistics_in_document | boolean | optional | true, false | Include back cover with statistics around the different revisions made in the document along with document score. Default is true. |
revisions_as_tracks | boolean | optional | true, false | Apply revisions in the document and make it available in track changes. Default is true. |
revisions_as_comments | boolean | optional | true, false | Apply revisions in the document as comments. Default is false. |
writing_advisor_as_comments | boolean | optional | true, false | Include 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
- 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
Parameter | type | mandatory/optional | Values | Notes |
---|---|---|---|---|
id | uuid | mandatory | various | Unique document id generated at the time of document submission |
filename | string | mandatory | various | Name of the submitted file |
status | string | mandatory | WAITING_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 |
message | string | optional | Various | Details of status as required. For example, Word limit per file restriction, File corrupted, etc. |
words | integer | mandatory | Various | The total number of words detected in the submitted document. |
error_id | integer | optional | Various | In case the document status is FAILED error_id field will provide the error number. |
error_report | object | mandatory | Various | Distribution of errors under various error categories |
language_score | number | mandatory | Various | A number between 0 and 100 that denotes the language quality score. |
total_corrections | integer | mandatory | Various | Total number of corrections suggested for the document |
total_suggestions | integer | mandatory | Various | Total number of suggestion comments added in the document |
total_sentences | integer | mandatory | Various | Total number of sentences in the document |
statistics_in_document | boolean | optional | true, false | Include back cover with statistics around the different revisions made in the document along with document score. Default is true. |
revisions_as_tracks | boolean | optional | true, false | Apply revisions in the document and make it available in track changes. Default is true. |
revisions_as_comments | boolean | optional | true, false | Apply revisions in the document as comments. Default is false. |
writing_advisor_as_comments | boolean | optional | true, false | Include 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
- 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
- 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.
- Proofread File API can currently process a maximum of 100,000 words in each request.
Trinka API Response Codes
200 - OK | Everything worked as expected. |
400 - Bad Request | The request was unacceptable, often due to missing a required parameter or file format not acceptable. |
401 - Unauthorized | No valid API key provided. |
403 - Forbidden | The API key doesn't have permissions to perform the request. |
429 - Too Many Requests | The API rate limit is exceeded. |
404 - Not Found | The requested resource doesn't exist. |
500 - Server error | Trinka server issue |