Save keywords

POST

/v1/keywords

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" ] } ] }'

• Production
• Development

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

• bearerAuth

Request Body^required

Media typeapplication/json

object

keywords

required

Array<object>

>= 1 items <= 50 items

object

term

required

The keyword text to save

string

>= 1 characters <= 255 characters

urls

URLs of the organization’s own to associate with this keyword. Any URL not already known is recorded.

Array<string>

<= 25 items

Example^generated

{
  "keywords": [
    {
      "term": "example",
      "urls": [
        "https://example.com"
      ]
    }
  ]
}

Responses

201

The saved keywords, including any that already existed

Media typeapplication/json

object

data

object

keywords

Array<object>

A keyword on the organization’s saved list — the same list the Tailwind dashboard’s Saved Keywords page shows.

object

id

Saved keyword ID

string

term

The keyword text

string

savedAt

When the keyword was added to the list

string format: date-time

urls

URLs of the organization’s own that this keyword is associated with

Array<string>

tags

Tags the organization has applied to this keyword

Array<object>

object

id

string

name

string

pinterestSearchVolume

Estimated monthly Pinterest search volume, or 0 when unknown

integer

commercialIntentScore

How strongly the term signals buying intent. Absent when Tailwind has no interest data for it.

number

detectedLanguage

Language detected for the term, e.g. “english”. Absent when Tailwind has no interest data for it.

string

meta

object

requestId

Unique request ID for debugging

string

Example^generated

{
  "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"
  }
}

400

Invalid request

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

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.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body"
  },
  "meta": {
    "requestId": "abc123"
  }
}

401

Authentication required or invalid bearer credentials

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

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.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "abc123"
  }
}

429

Rate limit exceeded

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

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.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit of 5000 requests exceeded. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "abc123"
  }
}