API Documentation

Api Documentation

Use this reference to integrate with the Dashword API. All endpoints return JSON. Requests must be authenticated with a Bearer API key over HTTPS.

The API is included on every plan, free accounts included — it is no longer limited to a paid tier. All you need is an account with a verified email address.

Writing with an AI agent? Dashword also runs an MCP server, so Claude, Cursor, and other MCP clients can call all of this without any integration code.

Base URL

https://app.dashword.com/api/v1

Authentication

The Dashword API uses API keys to authenticate requests. Create one on your API tokens page.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authenticated request:

curl https://app.dashword.com/api/v1/reports \
  -H 'Authorization: Bearer YOUR_API_KEY'

Notes:

{ "message": "Unauthenticated." }

Credits and rate limits

Available countries

Reports

Reports provide the competitive landscape for a given keyphrase and country, including competing URLs, keyword suggestions, and questions.

Create a report

Endpoint:
POST /reports
Parameters:
Example request:
curl -X POST https://app.dashword.com/api/v1/reports \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "keyphrase": "keto diet",
    "country": "us",
    "callback_url": "https://www.example.com/callback"
  }'
Response example:
{
    "id": "DVGR4qZKyva",
    "keyphrase": "keto diet",
    "status": "created",
    "country": "us",
    "callback_url": "https://www.example.com",
    "created_at": "2022-02-23T22:17:16.373260Z",
    "updated_at": "2022-02-23T22:19:46.171160Z"
}

Retrieve a report

Endpoint:
GET /reports/:id
Response example:
{
    "id": "DVGR4qZKyva",
    "keyphrase": "keto diet",
    "status": "completed",
    "country": "us",
    "urls": [
        {
            "position": 1,
            "url": "https://www.example.com/1",
            "title": "Example 1",
            "word_count": 558,
            "grade": "B+",
            "readability": "10th to 12th grade"
        },
        {
            "position": 2,
            "url": "https://www.example.com/2",
            "title": "Example 2",
            "word_count": 983,
            "grade": "B",
            "readability": "8th & 9th grade"
        },
        {
            "position": 3,
            "url": "https://www.example.com/3",
            "title": "Example 3",
            "word_count": 329,
            "grade": "D-",
            "readability": "7th grade"
        }
    ],
    "keywords": [
        {
            "keyword": "weight loss",
            "importance": 100,
            "min_occurrences": 2,
            "max_occurrences": 4
        },
        {
            "keyword": "keto",
            "importance": 86,
            "min_occurrences": 5,
            "max_occurrences": 11
        },
        {
            "keyword": "low carb diet",
            "importance": 84,
            "min_occurrences": 2,
            "max_occurrences": 4
        }
    ],
    "questions": [
        {
            "question": "What can you eat on the keto diet?",
            "search_volume": 1000
        },
        {
            "question": "Why keto diet is bad?",
            "search_volume": 800
        },
        {
            "question": "What are the main rules of Keto?",
            "search_volume": null
        }
    ],
    "callback_url": "https://www.example.com",
    "created_at": "2022-01-03T23:52:06.000000Z",
    "updated_at": "2022-01-03T23:59:05.000000Z"
}

List all reports

Endpoint:
GET /reports

Use the page query parameter to paginate through results (default page size shown in the response meta). For example: GET /reports?page=2.

Response example:
{
    "data": [
        {
            "id": "ry241xxP3ox",
            "keyphrase": "keto diet",
            "status": "completed",
            "country": "us",
            "callback_url": null,
            "created_at": "2022-02-04T03:47:58.000000Z",
            "updated_at": "2022-02-04T03:47:58.000000Z"
        },
        {
            "id": "OLwQYBpPzEA",
            "keyphrase": "best credit card",
            "status": "completed",
            "country": "us",
            "callback_url": null,
            "created_at": "2022-01-03T23:52:06.000000Z",
            "updated_at": "2022-01-03T23:59:05.000000Z"
        }
    ],
    "links": {
        "first": "https://app.dashword.com/api/v1/reports?page=1",
        "last": "https://app.dashword.com/api/v1/reports?page=1",
        "prev": null,
        "next": "https://app.dashword.com/api/v1/reports?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://app.dashword.com/api/v1/reports",
        "per_page": 15,
        "to": 15,
        "total": 10
    }
}

Callback URL

When generating a report, you have the option to provide a callback_url. This URL will be used to send a HTTP POST request once the report has been fully generated. The POST request is made to notify your application about the completion of the report generation process.

Setting Up the Callback URL

To set up the callback URL, include it as a parameter while creating a report using the POST /reports endpoint. The parameter is optional. If it's provided, it should be a full, valid URL, including the scheme (HTTP or HTTPS).

POST /reports

{
    "keyphrase": "keto diet",
    "country": "us",
    "callback_url": "https://www.example.com/callback"
}

The provided callback_url will be stored with the report and used to send a POST request once the report generation has completed.

POST Request Format

Once the report is ready, Dashword will send a HTTP POST request to the callback_url. The body of the POST request will contain a JSON payload with information about the completed report:

{
    "id": "DVGR4qZKyva",
    "keyphrase": "keto diet",
    "status": "completed",
    "country": "us",
    "callback_url": "https://www.example.com",
    "created_at": "2022-01-03T23:52:06.000000Z",
    "updated_at": "2022-01-03T23:59:05.000000Z"
}

Please note that the callback_url should be set up to accept POST requests and correctly handle the incoming JSON payload.

Handling Callback Requests

Your application should respond to the POST request with a 200 OK status code to acknowledge receipt of the callback. If Dashword does not receive a 200 OK response, the callback request may be retried.

Content Scoring

Score content

Score content (markdown or plain text) against an existing report to see overall grade, readability, and keyword usage coverage.

Endpoint:
POST /score
Parameters:

At least one of markdown or text must be provided.

Example request:
curl -X POST https://app.dashword.com/api/v1/score \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "report_id": "DVGR4qZKyva",
    "markdown": "# Keto Diet\nKeto is a low carb diet that..."
  }'
Response example:
{
    "report_id": "DVGR4qZKyva",
    "grade": "B+",
    "word_count": 245,
    "readability": "8th & 9th grade",
    "keywords": [
        {
            "keyword": "keto diet",
            "importance": 100,
            "occurrences": 6,
            "min_occurrences": 2,
            "max_occurrences": 4,
            "has_enough_usage": true
        },
        {
            "keyword": "low carb diet",
            "importance": 84,
            "occurrences": 1,
            "min_occurrences": 2,
            "max_occurrences": 4,
            "has_enough_usage": false
        }
    ]
}
Error responses:
{ "message": "Either markdown or text is required." }

{ "message": "Report not found." }