NAV Navbar
curl
  • Introduction
  • Authentication
  • Errors
  • Grammar Rule IDs
  • API Endpoints
  • 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.

    1. YOUR_APP_KEY: The unique key generated for this integration
    2. USER_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

    Spelling

    Verb

    Determiner

    Punctuation

    Pronoun

    Casing

    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:

    rulesApplied

    A JSON response representing a full breakdown of every grammatical error found in the input text.

    This response is structured as follows:

    summary

    A JSON response representing a summary of the grammatical errors found in the input text.

    This response is structured as follows:

    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.