Introduction
Welcome to the Perfect Tense API! Using our API, you can have full access to our grammar correcting services.
We currently have a Node.js and PHP SDK available. Both can be found in our public GitHub repository.
Authentication
To authorize a request, include the following information in your request header:
# You can just pass the correct header with each request
curl "API_END_POINT"
-H "Authorization: [USER_API_KEY]"
-H "AppAuthorization: [YOUR_APP_KEY]"
Perfect Tense uses a combination of two keys to authenticate and authorize an API request.
YOUR_APP_KEY
: The unique key generated for this integrationUSER_API_KEY
: The API key of the user for whom the request is being made
YOUR_APP_KEY
is generated when the integration is registered and must be sent with all requests. USER_API_KEY
is unique for each user. This value will vary depending on the use of your integration. If this integration is for personal use, send your own API key with each request (found here). If your integration will be used by many users, you must request their API key from them, and then send it with requests on their behalf.
Standalone API Users
To use our API for a standalone integration (only used by yourself), you must still register the integration to generate an APP key. Then, send the APP key along with your personal API key with each request.
Public API Use
To create an integration that will be used by multiple people, you must register the integration to generate an APP key. This APP key will be sent in the header of each request for authentication.
In addition to sending an APP key, you must also send each user's API key for requests on their behalf. Please direct users to our sign up page to create an account. Once they have created an account, their API key can be found on the home page. Your integration should prompt users for their API key and store them in a secure manner for future requests.
If you are creating an integration into your own personal service (as opposed to a public service such as Slack), consider using our affiliate program when directing users to our signup page.
Errors
The Perfect Tense API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is Malformed. |
401 | Unauthorized -- Your API or APP key is missing or invalid. |
403 | Forbidden -- You have gone over your daily API quota. |
404 | Not Found -- The api path could not be found. |
408 | Server Timeout -- Your request did not process under a time limit. |
422 | Unprocessable Entity - Your parameters are invalid. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
Grammar Rule IDs
Some API responses include a ruleId
field. These refer to specific grammar rules, and can be referenced through the following list:
Grammar
0.0
Other0.1
Superlative/Comparative0.2
Adverb Placement0.3
Double Negative0.4
End of Sentence Preposition0.5
Sentence Fragment0.6
Duplicate Words0.7
Missing Prepositions0.8
Missing To-Infinitive0.9
Prepositional Phrase0.10
Adjective Ordering
Spelling
1.0
Spell Check1.1
Contraction Apostrophe1.2
Number Suffix1.3
Hyphenated Phrase
Verb
2.0
Verb Agreement2.1
Gerund/Infinitive2.2
Bare Infinitive2.3
Missing Verb2.4
Gerund With Subordinating Conjunction2.5
Subjunctive Mood2.6
Incompatible Verb
Determiner
3.0
Definite/Indefinite Articles3.1
A/An3.2
Quantifier Misuse
Punctuation
4.0
Introductory Commas4.1
Independent Clauses Comma4.2
Subject Verb Comma4.3
Comma After Article4.4
Coordinate Adjectives Comma4.5
Compound Predicates Comma4.6
Spaces Before Punctuation4.7
Spaces After Punctuation4.8
Subordinate Conjunction Quotation4.9
Missing Question Mark4.10
Spaces Between Words4.11
Genitive Case4.12
Oxford Comma4.13
Comma Before Correlative Conjunction4.14
Comma After Interjection4.15
Possessive Noun4.16
Double Periods
Pronoun
5.0
Subject and Object5.1
Unnecessary Reflexive5.2
Missing Reflexive5.3
Who/Whom
Casing
6.0
Capitalize Beginning of Sentence
API Endpoints
Base API URL
https://api.perfecttense.com
All requests should be sent to the above URL with the correct endpoint specified.
POST /correct
Sample request for every response type. If no response type is provided, the default is 'corrected':
curl "https://api.perfecttense.com/correct" \
-H "Authorization: [USER_API_KEY]" \
-H "AppAuthorization: [YOUR_APP_KEY]" \
-H "Content-Type: application/json" \
-X POST \
-d '{"text": "This articl have some errors", "responseType": ["corrected", "grammarScore", "rulesApplied", "offset", "summary"]}'
Sample request with a custom
dictionary
word "articl" (ignoring spell check for that word!):
curl "https://api.perfecttense.com/correct" \
-H "Authorization: [USER_API_KEY]" \
-H "AppAuthorization: [YOUR_APP_KEY]" \
-H "Content-Type: application/json" \
-X POST \
-d '{"text": "This articl has an error", "options": {"dictionary": ["articl"]}}'
This endpoint is the core of our service. If the request is valid, Perfect Tense will check the 'text' parameter for any grammatical errors, and respond with the requested response types (see response format to the right).
Endpoint URL
https://api.perfecttense.com/correct
Query Parameters
Parameter | Required | Default | Description |
---|---|---|---|
text | true |
-- | Set it to the article you want to correct. Maximum size is 50,000 characters. |
responseType | false |
["corrected"] | Accepts a valid responseType as a single string or array of strings. |
options | false |
{} | Additional options for this request. See section Options for more information. |
Options
Parameter | Type | Default | Description |
---|---|---|---|
dialect | String | "american" | The English dialect to use for grammar correction. Currently supporting "american" and "british". |
dictionary | Array | [] | An array of additional dictionary words or phrases as Strings. These will effectively serve as a spell check ignore list. |
persist | Boolean | false |
If set to true , the result of this request will be added to your Saved Files collection, and a unique identifier for that file will be returned in the response. |
protecturls | Boolean | false |
If set to true , urls will be ignored. |
protectquotes | Boolean | false |
If set to true , phrases within single or double quotations will be ignored. |
protectcapitalized | Boolean | false |
If set to true , capitalized words will be ignored. |
Successful Response:
{
"id":"...",
"corrected": "...",
"grammarScore": 100.0,
"rulesApplied": [...],
"offset": [...],
"summary": {...},
"uid": "..."
}
Response Fields
Field | Type | Required | Description |
---|---|---|---|
id | String | true |
A unique identifier for this request. |
corrected | String | false |
A single String with all corrections applied to the input text. |
grammarScore | Number | false |
A numerical value representing a grammatical "score" for the input text. |
offset | Array | false |
A condensed breakdown of corrections made on each sentence in the input text. |
rulesApplied | Array | false |
A full breakdown of corrections made on each sentence in the input text. |
summary | Object | false |
A summary of all corrections made. |
uid | String | false |
A unique identifier for the newly created Saved File . Only provided if the persist option is set to true. A link to open the file in the editor can then be constructed as follows: https://app.perfecttense.com/editor?uid=[uid] |
corrected
Response:
{
"id": "...",
"corrected": "This article has some errors."
}
grammarScore
Response:
{
"id": "...",
"grammarScore": 24.1
}
offset
Response:
{
"id": "...",
"offset": [
{
"corrections": [
{
"options": [
{
"corrected": "article ",
"appliedRules": [
{
"ruleId": "1.0",
"message": "This phrase appears to be misspelled."
}
],
"isSuggestion": false
}
],
"affected": "articl ",
"offsetInSentence": 5
},
{
"options": [
{
"corrected": "has ",
"appliedRules": [
{
"ruleId": "2.0",
"message": "Consider changing the verb form."
}
],
"isSuggestion": false
}
],
"affected": "have ",
"offsetInSentence": 12
}
],
"sentenceOffset": 0,
"originalSentence": "This articl have some errors",
"correctedSentence": "This article has some errors"
}
]
}
rulesApplied
Response:
{
"id": "...",
"rulesApplied": [
{
"transformations": [
{
"ruleId": "1.0",
"message": "This phrase appears to be misspelled.",
"confidence": 1.0,
"tokensAdded": [
{
"id": 6,
"after": " ",
"value": "article"
}
],
"isSuggestion": false,
"hasReplacement": true,
"tokensAffected": [
{
"id": 2,
"after": " ",
"value": "articl"
}
],
"sentAfterTransform": "This article have some errors"
},
{
"ruleId": "2.0",
"message": "Consider changing the verb form.",
"confidence": 1.0,
"tokensAdded": [
{
"id": 7,
"after": " ",
"value": "has"
}
],
"isSuggestion": false,
"hasReplacement": true,
"tokensAffected": [
{
"id": 3,
"after": " ",
"value": "have"
}
],
"sentAfterTransform": "This article has some errors"
}
],
"originalSentence": [
{
"id": 1,
"after": " ",
"value": "This"
},
{
"id": 2,
"after": " ",
"value": "articl"
},
{
"id": 3,
"after": " ",
"value": "have"
},
{
"id": 4,
"after": " ",
"value": "some"
},
{
"id": 5,
"after": "",
"value": "errors"
}
],
"correctedSentence": "This article has some errors"
}
]
}
summary
Response:
{
"id": "...",
"summary": {
"numCorrections": 2,
"corrections": [
{
"type": "Verb Agreement",
"count": 1,
"ruleId": "2.0"
},
{
"type": "Spell Check",
"count": 1,
"ruleId": "1.0"
}
]
}
}
Available Response Types
Each request may send an array responseType
specifying which optional fields to include in the response.
corrected
A single string with all (non-suggestion) corrections applied to the input text.
grammarScore
A number from 0.0 to 100.0 indicating the grammatical "score" for the input text, based on the errors found.
offset
A JSON response representing a condensed summary of grammatical errors found in the input text. Overlapping corrections on the same token will be flattened into one correction (as opposed to reported individually as in the rulesApplied
response). Due to this condition, this response type is able to provide character offsets for corrections, which may be useful for some integrations.
This response is structured as follows:
offset
: A top level Array ofSentence
Objects parsed from the original input. Each element contains a condensed summary of all grammatical errors found in the sentence. Elements maintain their order from the original input.originalSentence
: A String containing the original input sentence.sentenceOffset
: A Number representing the character offset of the sentence in the original input text.correctedSentence
: A String representing a final "corrected" version of the sentence, with all non-suggestion transformations applied.corrections
: An Array of errors found in the sentence and condensed information to correct them.affected
: A String containing the text in the original sentence where the error was found.offsetInSentence
: A Number representing the character offset of theaffected
phrase in this sentence.options
: An Array of "Correction Options" for this mistake.corrected
: A String containing the correction for this error.isSuggestion
: A Boolean specifying if this correction is a "suggestion" (lower confidence).appliedRules
: An Array of grammar rules in the order they were applied to theaffected
phrase to reach thecorrected
result.ruleId
: A String indicating the unique id for the grammar rule that made this transformation. See sectionGrammar Rule IDs
.message
: A String explaining the grammar mistake that was found.
rulesApplied
A JSON response representing a full breakdown of every grammatical error found in the input text.
This response is structured as follows:
rulesApplied
: A top level Array ofSentence
Objects parsed from the original input. Each element contains a full breakdown of all grammatical errors found in the sentence. Elements maintain their order from the original input.originalSentence
: An Array ofToken
Objects representing a tokenized version of the original input sentence.id
: A Number used as a unique id for this token in the sentence.value
: A String containing the text of this token.after
: A String containing the text after this token (typically whitespace or an empty String).correctedSentence
: A String representing a final "corrected" version of the sentence, with all non-suggestion transformations applied.transformations
: An Array of grammatical "transformations" representing errors found in the sentence and information to correct them.ruleId
: A String indicating the unique id for the grammar rule that made this transformation. See sectionGrammar Rule IDs
.message
: A String explaining the grammar mistake that was found.isSuggestion
: A Boolean specifying if this transformation is a "suggestion" (lower confidence).tokensAffected
: An Array ofToken
Objects representing the phrase that this transformation is correcting.tokensAdded
: An optional Array ofToken
Objects that represent the replacement for thetokensAffected
(the corrected version).hasReplacement
: A Boolean specifying whethertokensAdded
contains a replacement for thetokensAffected
. If False,tokensAdded
should be ignored, and this transformation represents a "remark" on thetokensAffected
. If True,tokensAdded
should replace thetokensAffected
.sentAfterTransform
: A String representing the corrected version of the sentence after this transformation has been applied.
summary
A JSON response representing a summary of the grammatical errors found in the input text.
This response is structured as follows:
summary
: A top level Object containing the summary responsenumCorrections
: The total number of corrections made on the input text.corrections
: An Array ofCorrection
Objects summarizing an individual correction type.type
: A String indicating the type of correction that was made.count
: A Number representing the number of occurrences of this type of correction.ruleId
: A String indicating the unique id for this grammar rule.
GET /usage
This endpoint provides User's API limit information. It shows the max number of API requests available per day, and how many are remaining for today.
curl "https://api.perfecttense.com/usage" \
-H "Authorization: [USER_API_KEY]" \
-H "AppAuthorization: [YOUR_APP_KEY]"
Endpoint URL
https://api.perfecttense.com/usage
Query Parameters
This endpoint takes NO parameters.
Successful Response:
{
"apiLimitPerDay": 300,
"apiRemainToday": 294,
"resetTime": 15896
}
Response Fields
Field | Type | Required | Description |
---|---|---|---|
apiLimitPerDay | Number | true |
A number representing your daily API limit. |
apiRemainToday | Number | true |
A number showing your API use for today. |
resetTime | Number | true |
Unix Timestamp of the next daily API limit reset. |