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.

Base URL

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

Authentication

The Dashword API uses API keys to authenticate requests.

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:

• Send Authorization: Bearer YOUR_API_KEY with every request.
• For POST/PUT endpoints, send Content-Type: application/json and a JSON body.
• Unauthorized requests return 401 with a JSON error, for example:

{ "message": "Unauthenticated." }

Available countries

• au (Australia)
• ca (Canada)
• gb (United Kingdom)
• ir (Ireland)
• nz (New Zealand)
• sg (Singapore)
• us (United States)

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:

• keyphrase required - The keyword phrase
• country required - Two-letter code from the available countries
• callback_url optional - A valid URL where we'll send a webhook once the report is completed

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:

• report_id required - The report ID returned by the Reports API
• markdown optional - Markdown content to score. Required if text is not provided
• text optional - Plain text content to score. Required if markdown is not provided

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:

• 422 (validation)

{ "message": "Either markdown or text is required." }

• 404 (report not found or not accessible)

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