Connect a feed

POST

/v1/feeds

const url = 'https://api-v1.tailwind.ai/v1/feeds';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"feedUrl":"example","accountId":"example","keywords":["example"],"designTier":"basic","premiumStyle":"image-highlight","generationFrequency":"every-3-days","autoRegenerate":true}'
};

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/feeds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "feedUrl": "example", "accountId": "example", "keywords": [ "example" ], "designTier": "basic", "premiumStyle": "image-highlight", "generationFrequency": "every-3-days", "autoRegenerate": true }'

Subscribe to an RSS feed. The feed’s current posts are snapshotted as the baseline, so nothing already published generates a Pin — only posts appearing on a later watcher run do.

The watcher runs once a day and creates each Pin as a draft for review; it never schedules or publishes. Generated Pins consume SmartPin credits at the same rate as manual ones, so connecting many feeds can drive credit use.

feedUrl must be an actual feed. Use preview-feed first when you only have a site URL.

accountId must name a currently connected Pinterest account: a feed assigned to a disconnected one would be skipped by the watcher every day without any error, so this is refused with 400 rather than accepted silently.

Authorizations

bearerAuth

Request Body^required

application/json

object

feedUrl

required

A resolved RSS or Atom feed URL. Use preview-feed to turn a site URL into one.

string

<= 2048 characters

accountId

required

Pinterest account the generated Pins are assigned to, from list-accounts.

string

keywords

Applied to every Pin this feed generates.

Array<string>

<= 50 items

designTier

Defaults to basic. premium requires premiumStyle.

string

Allowed values: basic premium no-template

premiumStyle

Required when designTier is premium, and rejected otherwise.

string

nullable

Allowed values: image-highlight text-highlight minimalist artistic professional natural

generationFrequency

string

Allowed values: every-3-days weekly every-2-weeks monthly

autoRegenerate

boolean

Responses

201

The feed was connected

application/json

object

data

object

feed

A connected RSS feed subscription.

object

required

Feed ID. Pass to get-feed, update-feed, delete-feed.

string

accountId

required

Pinterest account the generated Pins are assigned to.

string

feedUrl

required

string

hostname

required

string

title

required

The feed’s own title, when it declares one.

string

nullable

keywords

required

Keywords applied to every Pin this feed generates.

Array<string>

designTier

required

Design treatment for generated Pins. template-match is readable but cannot be set through this API — it is not generally available.

string

Allowed values: basic premium no-template template-match

premiumStyle

required

Set only on the premium tier; null otherwise.

string

nullable

Allowed values: image-highlight text-highlight minimalist artistic professional natural

generationFrequency

required

How often a generated Pin is redesigned, when autoRegenerate is on. Not how often the feed is checked — that is daily.

string

Allowed values: every-3-days weekly every-2-weeks monthly

autoRegenerate

required

Whether generated Pins are periodically redesigned.

boolean

status

required

A paused feed generates nothing, but is also not polled — so posts published while it is paused are treated as new on resume.

string

Allowed values: active paused

lastPolledAt

required

ISO 8601 timestamp of the last watcher run over this feed, or null if it has not run yet.

string

nullable

lastFailureReason

required

Why the last poll failed, or null. A feed that keeps failing here is usually unreachable rather than empty.

string

nullable

smartPinCount

required

SmartPins generated from this feed so far.

number

createdAt

required

ISO 8601

string

updatedAt

required

ISO 8601

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "feed": {
      "designTier": "basic",
      "premiumStyle": "image-highlight",
      "generationFrequency": "every-3-days",
      "status": "active"
    }
  }
}

400

Invalid request

application/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

application/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

string

meta

object

requestId

Unique request ID for debugging

string

Example

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

404

Resource not found

application/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

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Account not found"
  },
  "meta": {
    "requestId": "abc123"
  }
}

409

This organization has already connected this feed

application/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

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "CONFLICT",
    "message": "You've already connected this feed."
  },
  "meta": {
    "requestId": "abc123"
  }
}

413

The feed was fetched and parsed, but the result is too large to process. Retrying returns the same feed, so this needs a smaller one.

application/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

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "That feed is too large for Tailwind to process. Try a feed with fewer or smaller entries."
  },
  "meta": {
    "requestId": "abc123"
  }
}

422

The document was fetched but is not a usable RSS or Atom feed. Retrying will not help.

application/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

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "The RSS feed could not be parsed. It may be malformed or in an unsupported format."
  },
  "meta": {
    "requestId": "abc123"
  }
}

424

The site could not be read. Either it did not respond, or its firewall refused us — the message says which, and a bot-protection refusal names the user agent to allowlist.

application/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

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "FAILED_DEPENDENCY",
    "message": "This site's firewall or bot protection is blocking Tailwind from reading the feed. Ask your security provider to allow the TailwindApp-SiteIndexer user agent, then try again."
  },
  "meta": {
    "requestId": "abc123"
  }
}

429

Rate limit exceeded

application/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

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

504

The site did not answer within the fetch budget. Safe to retry.

application/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

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "The site took too long to respond. Please try again."
  },
  "meta": {
    "requestId": "abc123"
  }
}

Connect a feed

Authorizations

Request Bodyrequired

Responses

201

Example

400

Example

401

Example

404

Example

409

Example

413

Example

422

Example

424

Example

429

Example

504

Example

Request Body^required