Save keywords
const url = 'https://api-v1.tailwind.ai/v1/keywords';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"keywords":[{"term":"example","urls":["https://example.com"]}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api-v1.tailwind.ai/v1/keywords \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "keywords": [ { "term": "example", "urls": [ "https://example.com" ] } ] }'Add keywords to the organization’s saved list. Matching is case-insensitive: a term already on the list is returned as it is stored rather than duplicated, so an overlapping batch is safe to re-send. Saving keywords does not consume credits.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
object
The keyword text to save
URLs of the organization’s own to associate with this keyword. Any URL not already known is recorded.
Examplegenerated
{ "keywords": [ { "term": "example", "urls": [ "https://example.com" ] } ]}Responses
Section titled “Responses”The saved keywords, including any that already existed
object
object
A keyword on the organization’s saved list — the same list the Tailwind dashboard’s Saved Keywords page shows.
object
Saved keyword ID
The keyword text
When the keyword was added to the list
URLs of the organization’s own that this keyword is associated with
Tags the organization has applied to this keyword
object
Estimated monthly Pinterest search volume. Absent when Tailwind has no volume data for the term; treat a missing value as unknown, not as zero demand.
How strongly the term signals buying intent. Absent when Tailwind has no interest data for it.
Language detected for the term, e.g. “english”. Absent when Tailwind has no interest data for it.
object
Unique request ID for debugging
Examplegenerated
{ "data": { "keywords": [ { "id": "example", "term": "example", "savedAt": "2026-04-15T12:00:00Z", "urls": [ "example" ], "tags": [ { "id": "example", "name": "example" } ], "pinterestSearchVolume": 1, "commercialIntentScore": 1, "detectedLanguage": "example" } ] }, "meta": { "requestId": "example" }}Invalid request
object
object
Error code
Error message
Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.
Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.
object
Unique request ID for debugging
Example
{ "error": { "code": "BAD_REQUEST", "message": "Invalid request body" }, "meta": { "requestId": "abc123" }}Authentication required or invalid bearer credentials
object
object
Error code
Error message
Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.
Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.
object
Unique request ID for debugging
Example
{ "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }, "meta": { "requestId": "abc123" }}Rate limit exceeded
object
object
Error code
Error message
Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.
Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.
object
Unique request ID for debugging
Example
{ "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Daily rate limit of 10000 requests for this organization exceeded. Resets at midnight UTC." }, "meta": { "requestId": "abc123" }}Headers
Section titled “Headers”Seconds until the daily limit resets at midnight UTC.