Topic Research API

Quickstart

cURL

curl --location 'https://workflow.api.kwrds.ai/topic-research' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data '{
    "topic": "electric cars",
    "search_country": "en-US"
}'

To increase your API limits, please choose your plan right from our pricing page.

Introduction

The Topic Research API generates topic structures with keyword research data delivered in Excel format.

Endpoints

POST /topic-research

Create a topic research job.

Base URL: https://workflow.api.kwrds.ai

Request Headers

X-API-KEY: (Required) Your API key for authentication.
Content-Type: (Required) Must be application/json.

Request Body

topic: (Required) Main topic to research. Example: "figma", "vegan recipes".
search_country: (Optional) Country code for localization (e.g., en-US). Default: en-US.
max_children: (Optional) Number of subtopics to generate (1-50). Default: 10.
manual_pages: (Optional) Array of custom subtopics to include. Example: ["tesla model 3"]. Default: [].

Example Request

cURL

curl --location 'https://workflow.api.kwrds.ai/topic-research' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data '{
    "topic": "figma",
    "search_country": "en-US"
}'

Response (202 - Job Created)

JSON

{
  "job_id": "60965750-9e39-4a6f-af50-20fa60603d81"
}

Use the job_id to check status via GET /topic-research/{jobId}.

Response (200 - Completed)

If results are already available, you'll receive the full response immediately:

JSON

{
  "job_id": "312682ede30b4f7467edd6d752ed562e67c512679338e13d3f446408396e9fe1",
  "status": "DONE",
  "topic": "figma",
  "search_country": "en-US",
  "max_children": 10,
  "created_at": 1762387187138,
  "updated_at": 1762387716945,
  "final_report_url": "https://...",
  "keyword_results": [...]
}

GET /topic-research/{jobId}

Check job status and retrieve results.

Example Request

cURL

curl --location 'https://workflow.api.kwrds.ai/topic-research/60965750-9e39-4a6f-af50-20fa60603d81' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE'

Response (Processing)

JSON

{
  "job_id": "60965750-9e39-4a6f-af50-20fa60603d81",
  "status": "PROCESSING",
  "topic": "electric cars",
  "created_at": 1762046547271,
  "final_report_url": null
}

Response (Completed)

JSON

{
  "job_id": "60965750-9e39-4a6f-af50-20fa60603d81",
  "status": "DONE",
  "topic": "electric cars",
  "created_at": 1762046547271,
  "updated_at": 1762046729184,
  "final_report_url": "https://..."
}

Response Fields:

status: PROCESSING, DONE, or FAILED
final_report_url: Download URL for Excel report (available when DONE)

GET /topic-research/jobs

List all jobs for your account.

Example Request

cURL

curl --location 'https://workflow.api.kwrds.ai/topic-research/jobs' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE'

Query Parameters

limit: (Optional) Max results to return. Default: 20.

Response

JSON

{
  "jobs": [
    {
      "job_id": "60965750-9e39-4a6f-af50-20fa60603d81",
      "status": "DONE",
      "topic": "electric cars",
      "created_at": 1762046547271,
      "final_report_url": "https://..."
    }
  ],
  "count": 1
}

Complete Example

bash

#!/bin/bash

API_KEY="YOUR_API_KEY_GOES_HERE"
BASE_URL="https://workflow.api.kwrds.ai"

# Create job
RESPONSE=$(curl -s -X POST "$BASE_URL/topic-research" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "sustainable fashion",
    "search_country": "en-US"
  }')

JOB_ID=$(echo $RESPONSE | jq -r '.job_id')
echo "Job created: $JOB_ID"

# Poll for completion
while true; do
  STATUS_RESPONSE=$(curl -s "$BASE_URL/topic-research/$JOB_ID" \
    -H "X-API-Key: $API_KEY")

  STATUS=$(echo $STATUS_RESPONSE | jq -r '.status')

  if [ "$STATUS" = "DONE" ]; then
    REPORT_URL=$(echo $STATUS_RESPONSE | jq -r '.final_report_url')
    echo "Download: $REPORT_URL"
    break
  fi

  sleep 30
done

Error Responses

401 Unauthorized

JSON

{
  "error": "X-API-Key header required"
}

400 Bad Request

JSON

{
  "error": "topic is required"
}

404 Not Found

JSON

{
  "error": "Job not found"
}

429 Too Many Requests

JSON

{
  "error": "Monthly quota exceeded for topic research"
}

Support

For questions or support, contact hello@kwrds.ai.