SoftSolzSoftSolz
HomeAPI GuideAPI ReferenceWidget Tester

Track a keyword for a website

409 already_tracked means it is already on the list; 409 tracked_cap_reached means the cap is reached. The optional research fields are kept as your tool figures, labelled with source_label. To add many keywords at once use the bulk endpoint.

POSThttps://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/keywords

Recent Requests

Kept only in this browser
TimeStatusTook
Send a request with Try it to see it here.

Path Params

site_idstringrequired

Headers

Authorizationstringrequired

Bearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

query_textstringrequired

The search to track.

notesstring | null

Your notes about the keyword, up to 1000 characters.

source_labelstring | null

Where the research came from, up to 80 characters. Shown as "From <source>".

their_monthly_searchesinteger | null

Monthly searches as estimated by your research tool, 0 or more. Stored and shown as that tool estimate, never as a Google figure.

their_difficultyinteger | null

Difficulty from 0 to 100 as scored by your research tool. Stored and shown as that tool estimate.

target_urlstring | null

The page that should rank for the keyword: a full address on the website domain (with or without www) or a path starting with /. Anything else is refused with 400 target_url_not_on_site.

Response

Response Body

idstringTracked keyword id. Use it as keyword_id.
site_idstringThe website it belongs to.
query_textstringNormalised search text.
notesstring | nullYour notes about the keyword, up to 1000 characters.
source_labelstring | nullWhere the research came from, up to 80 characters. Shown as "From <source>".
their_monthly_searchesinteger | nullMonthly searches as estimated by your research tool, 0 or more. Stored and shown as that tool estimate, never as a Google figure.
their_difficultyinteger | nullDifficulty from 0 to 100 as scored by your research tool. Stored and shown as that tool estimate.
target_urlstring | nullThe page that should rank, as a full address.
added_viastringHow it was added: dashboard, api or connected_app.
added_by_labelstring | nullThe app or key that added it.
created_atstringWhen tracking started.
updated_atstringSend it back as expected_updated_at when you change the keyword.

Request

curl --request POST \
--url https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/keywords \
--header 'Authorization: Bearer sk_live_your_key' \
--header 'Content-Type: application/json' \
--data '{
"query_text": "sourdough starter",
"notes": "Main money keyword.",
"source_label": "Ahrefs via Claude",
"their_monthly_searches": 2400,
"their_difficulty": 35,
"target_url": "/sourdough-starter"
}'

Credentials

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 201

{
"data": {
"id": "3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23",
"site_id": "3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23",
"query_text": "sourdough starter",
"notes": "Main money keyword.",
"source_label": "Ahrefs via Claude",
"their_monthly_searches": 2400,
"their_difficulty": 35,
"target_url": null,
"added_via": "connected_app",
"added_by_label": "Claude",
"created_at": "2026-09-01T09:00:00.000Z",
"updated_at": "2026-09-01T09:00:00.000Z"
}
}