API Developer Portal Documentation

Overview

Free Plan

Cortical.io Natural Language API – Free Tier is designed for light users and developers who are just getting started. Ideal for initial testing and small-scale projects, this plan allows for less than 20,000 requests per month.

• Maximum data size: 10KB per request.
• Rate limit: Maximum of 2 requests per second.

Starter Plan

The Starter Plan of the Cortical.io Natural Language API caters to medium-scale projects and businesses, accommodating up to 200,000 requests per month. It is a perfect choice for developers and businesses that require a bit more power and support than the Free Tier offers.

• Maximum data size: 10KB per request.
• Rate limit: Maximum of 5 requests per second.

Pro Plan

Suited for businesses that are expanding and need an intermediate solution between the Starter and Enterprise Plans. Up to 1,000,000 requests per month.

• Maximum data size: 10KB per request.
• Rate limit: Maximum of 10 requests per second.

Enterprise Plan

Aimed at large enterprises and high-demand applications, the Enterprise Plan of the Cortical.io Natural Language API supports an impressive 4,000,000 requests per month. This plan is tailored for businesses that need high throughput and premium support.

• Maximum data size: 10KB per request.
• Rate limit: Maximum of 15 requests per second.

Transferability of quotas

Custom Plan

For users or businesses with needs exceeding the plans described here, please contact api-sales@cortical.io for a customized solution and pricing.

Trying Out the NLP API Product

To select a plan, navigate to the product page on the Cortical.io Developer Portal.

Choose the desired Plan and click the 'Start With This Plan' button. This will add the product subscription to your shopping cart, where you will pair the product with an application and submit a request. In the cart, ensure you have selected the correct product and plan. Then, either create a new app or choose an existing app for your product.

Click ‘Submit Request.’ For paid plans, the system will then redirect you to the payment page where you can enter payment information and confirm your subscription.

Viewing Product & Plan Details

On the ‘My Apps’ page, click on the name of the app you paired with the product in the previous section. If your request has been approved, it will appear under the ‘Approved access’ section. Your subscription plan details, including the product quota (maximum number of API calls per month), rate (maximum throughput speed), and Token ID will be listed under ‘Access and Credentials info.'

Token Management

Token ID: This unique ID is required for every API request you make. Use the ‘Rotate’ button if you wish to substitute the current token with a new Token ID.

Utilizing the NLP API Product

Click on the ‘NLP API Product’ link under ‘Access and Credentials info’ (you can also use the ‘NLP API’ link at the top of the Developer Portal). Then, select the ‘API Specifications’ tab and the NLP API product will be displayed. As the NLP API initializes, the available endpoints will be displayed on the left. Select any endpoint to delve into its details, such as description, parameters, response codes, example requests, responses, and to initiate a new request.

For code examples in your chosen programming language, utilize the drop-down menu under ‘Example Requests/Responses.’

Generating an API Request

Inline Panel: Each endpoint page contains a panel on the right that provides sections for Authorization (Auth), Parameters (where applicable) and Body. Once all fields are complete, click 'Send API Request' to generate the request.

Third-party API Client: You can also employ any third-party API client compatible with the supported programming languages to send a request to a Cortical.io NLP API endpoint URL.

Important: For every request, it is imperative to include the Token ID, whether you are using the Parameters section or a third-party API client.

The latest API documentation is always available on the developer portal by logging into your registered account and navigating to: https://api.cortical.io/portal/catalogue-products/nlp-api-product#/

Error Handling

When using our API, it is essential to know how errors are handled. Please refer to our error code guide in the Appendix to understand the different HTTP status codes and their meanings. Additional information can be provided by the JSON response containing further details about the error.

If the error persists for an extended period, contact our support team at api-support@cortical.io.

Feedback and Support

We value your feedback. If you have any questions, encounter any issues, or have suggestions to improve our service, please contact our support team.

GET/…/supported-languages

Description: This endpoint returns the list of supported languages. The two letter language codes can then be used as input for other endpoints. The service supports semantic operations for these languages.

{
    "supported_languages": [
        "en",
        "de"
    ]
}

POST/…/keywords

Description: This endpoint extracts the semantically most relevant words from a given text. The number of keywords parameter can ideally be selected in proportion to the length of the text (the default is 10 terms).

{
    "supported_languages": [
        "en",
        "de"
    ]
}

{
"keywords": [
    {
      "word": "string",
      "document_frequency": 0,
      "pos_tags": [
        "NOUN"
      ],
      "score": 0
    }
  ],
  "language": "en"
}

POST/…/compare

Description: This endpoint computes the semantic similarity between two texts, and returns the value in a range between 0 and 1.

{
  "similarity": 0.7,
  "languages": [
    "en",
    "en"
  ]
}

{
  "message": "Language 'zh' is not supported."
}

POST/…/language

Description: This endpoint detects the language of a given text by using using a fastText language detection model. The model is not precise on very short texts (a few words are needed). If the input text contains multiple languages, the endpoint will only return the language with the highest confidence level.

{
  "language": "en"
}

POST/…/labels

Description: This endpoint identifies the most similar words for a submitted text. The text-fingerprint is compared to all known word-fingerprints and the words with the highest similarities are returned.

{
  "labels": [
    {
      "word": "string",
      "document_frequency": 0,
      "pos_tags": [
        "NOUN"
      ]
    }
  ],
  "language": "en"
}

{
  "message": "Language 'zh' is not supported."
}

POST/…/segmentation

Description: This endpoint breaks down a given text into smaller segments, referred to as 'topical paragraphs.’ These 'topical paragraphs' are computed by combining adjacent segments until a shift in linguistic cues or topics is identified.

{
  "segments": [
    "string"
  ],
  "language": "en"
}

{
  "message": "Language 'zh' is not supported."
}