メインコンテンツまでスキップ

API Guide

🚀Welcome to Shodo API documentation🚀

Command​

You can use Shodo's API from shodo command. For example, you can proofread Japanese in a Markdown file.

$ pip install shodo
$ shodo login
$ shodo lint README.md

For more details, refer shodo command's README.

API root​

Specify Organization slug and project name.

https://api.shodo.ink/@{organization}/{project}/

Authorization​

First, issue Bearer tokens in the "API integration" settings page of Shodo's project.

Specify the token on Authorization header.

Authorization: Bearer {token}

Lint/Proofreading API​

This is API to proofread Japanese texts.

API URL：https://api.shodo.ink/@{organization}/{project}/lint/

POST a Japanese body to the proofreading API. Up to 40,000 characters are allowed.

{
  "body": "校正する本文"
}

Option:

  • type: Specify body type as text (text, Markdown), html (HTML). (Default is text)

Response​

{
  "lint_id": "6d639e5f-8bfe-43d7-ac24-8bb6b97ba936",
  "monthly_amount": 1000000,
  "current_usage": 116049,
  "len_body": 8429,
  "len_used": 8112
}

Shodo runs proofreading asynchronously. The lint_id is used to get results of proofreading.

For example, you can use httpie to call this API.

$ http -A bearer -a d8eb...3359 https://api.shodo.ink/@org/project/lint/ text="校正する本文"

Counting and caching​

Shodo counts only Japanese sentences in the submitted body as the number of characters used. The number of characters will be less than the length of all submitted body.

Submitted sentences will be cached, so if the same sentence is submitted again, Shodo won't count them as monthly usage.

Each response of the proofreading API has the following meaning.

  • lint_id: ID to get the result of the proofreading.
  • monthly_amount: Number of characters available in the API (per month).
  • current_usage: Number of characters used this month.
  • len_body: Length of Japanese sentences of the submitted body.
  • len_used: Used number of character (subtracting the cache).

For example, if all the cache is used, len_used will be 0. The cache is valid for about 30 minutes, but the cache time is not guaranteed. Please be assured that the cache of the text is managed in a way that it is not leaked or affected by other users.

HTML Input​

In Shodo, you can use HTML in the body. When HTML is specified, the body text of block elements will be proofread. Please note that inline elements and attribute values are ignored. Also, the target of proofreading must be included within some HTML elements.

$ http ... body="<p>これは本文です</p>" type="html"

The structure of the body will be analysied as follows:

  • <h1> to <h6>: Headings
  • <li>: List (<li><p>...</p></li> is also considered as a list)
  • <div>, <p>, <figcaption>, etc.: Paragraphs

Additionally, the character limit for input (42,000 characters) does not consider HTML tags.

Result API​

You can get results of proofreading.

API URL：https://api.shodo.ink/@{organization}/{project}/lint/{lint_id}/

Response​

{
  "messages": [
    {
      "after": "",
      "before": "が",
      "code": "ai_recommend",
      "from": {
        "ch": 21,
        "line": 669
      },
      "index": 17619,
      "message": "もしかしてAI",
      "severity": "error",
      "operation": "delete",
      "score": 0.9886295795440674,
      "to": {
        "ch": 22,
        "line": 669
      }
    }
  ],
  "status": "done",
  "updated": 1658379913
}

Command example:

$ http -A bearer -a d8eb...3359 https://api.shodo.ink/@org/project/lint/6d639e5f-8bfe-43d7-ac24-8bb6b97ba936/

Response detail​

  • messages:
    • code: Proofreading code
    • message: Proofreading message detail
    • from: Starting position（{ line: line number, ch: column number }）. Starting from 0.
    • to: Ending position（{ line: line number, ch: column number }）. Starting from 0.
    • index: Index number starting from 0.
    • before: Text with Japanese problem.
    • after: Recommended text.
    • operation: Which you should "delete", "replace", or "keep" the word. null if it's unpredictable.
    • score: Probability of proofreading changes
    • severity: Severity of the message (error, warning, or info).
  • status: The status of proofreading process. done, processing, or failed.
  • updated: Last updated datetime (UNIX timestamp)

Proofreading multiple sentences​

Shodo's API allows you to submit multiple texts at once. Instead of body, you can specify a list of body texts with the parameter bulk_body.

{
  "bulk_body": ["本文1", "本文2"]
}

The messages param of the proofreading result will be the result of each body. For example, if bulk_body contains two bodies, the messages will be a list of two elements.

{
  "messages": [
    [
      {
        "after": "",
        "before": "が",
        "from": {
          "ch": 0,
          "line": 3
        }
      }
    ],
    []
  ],
  "status": "done",
  "updated": 1658379913
}

Usage API​

Usage API will return monthly usage of the organization. The response will contain last 12 months of usage aggregation.

API URL：https://api.shodo.ink/@{organization}/{project}/usage/

Response​

{
  "usage": [
      {"year":  2023, "month":  6, "amount":  24000},
      {"year":  2023, "month":  5, "amount":  28000},
      {"year":  2023, "month":  4, "amount":  32000},
      {"year":  2023, "month":  3, "amount":  150129},
      {"year":  2023, "month":  2, "amount":  4003},
      {"year":  2023, "month":  1, "amount":  44000},
      {"year":  2022, "month":  12, "amount":  48081},
      {"year":  2022, "month":  11, "amount":  52000},
      {"year":  2022, "month":  10, "amount":  56000},
      {"year":  2022, "month":  9, "amount":  60022},
      {"year":  2022, "month":  8, "amount":  64330},
      {"year":  2022, "month":  7, "amount":  68830},
      {"year":  2022, "month":  6, "amount":  72120}
  ],
  "monthly_mount":  160000 
}

For example, you can use httpie to call this API.

$ http -A bearer -a d8eb...3359 https://api.shodo.ink/@org/project/usage/

Terms API​

You can set terms and variants for proofreading API. The terms and variants set by this API are the same as those set by the Shodo screen.

API URL：https://api.shodo.ink/@{organization}/{project}/terms/

Response​

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 100000,
            "description": "",
            "text": "Shodo",
            "variants": [{"text":  "ShoDo"}],
            "severity": "error",
            "fuzzy_complement": false
        }
    ]
}

Command example:

$ http -A bearer -a d8eb...3359 https://api.shodo.ink/@org/project/terms/

Response detail​

results contains the list of terms. If there are more data, next will contain the next page number (?page=2, etc.).

  • id：Term ID
  • description：Description for the term (won't be used for AI proofreading)
  • text：Term text
  • variants：List of variants（each variants will be like {"text": "VariantText"}）
  • severity: Severity of message for the term ("error", "warning" or "info")
  • fuzzy_complement： Whether to automatically detect fuzzy complements

Add terms and variants​

You can add terms and variants by POST method.

$ http -A bearer -a d8eb...3359 https://api.shodo.ink/@org/project/terms/ text="Shodo"

You can specify text , description , variants , severity, fuzzy_complement params.

Term detail API​

You can get the detail of the term by the following API.

API URL：https://api.shodo.ink/@{organization}/{project}/terms/{id}/

Command example:

$ http -A bearer -a d8eb...3359 https://api.shodo.ink/@org/project/terms/1/

Response detail​

{
    "id": 100000,
    "description": "",
    "text": "Shodo",
    "variants": [{"text":  "ShoDo"}],
    "severity": "error",
    "fuzzy_complement": false
}

Update terms and variants​

You can update terms and variants by PUT method.

$ http -A bearer -a d8eb...3359 PUT https://api.shodo.ink/@org/project/terms/1/ text="SHODO"

You can specify text , description , variants , severity, fuzzy_complement params.

Delete terms and variants​

You can delete terms and variants by DELETE method.

$ http -A bearer -a d8eb...3359 DELETE https://api.shodo.ink/@org/project/terms/1/

Delete all terms​

You can delete all terms and variants set in the project by the following API.

API URL：https://api.shodo.ink/@{organization}/{project}/terms/deleteall/

Send POST method to the API URL.

Command example:

$ http -A bearer -a d8eb...3359 POST https://api.shodo.ink/@org/project/terms/deleteall/

Post file API​

Please refer APIドキュメント file (not translated yet).