List feed subscriptions

GET

/v1/feeds

const url = 'https://api-v1.tailwind.ai/v1/feeds?limit=50';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api-v1.tailwind.ai/v1/feeds?limit=50' \
  --header 'Authorization: Bearer <token>'

The organization’s connected RSS feeds, newest first. Each one generates a SmartPin draft for every new post the daily watcher finds.

Feeds are org-scoped, not per-account: every feed names the Pinterest account its Pins are assigned to, and accountId filters by it. Results are paginated; pass the returned nextCursor to read further.

Authorizations

bearerAuth

Parameters

Query Parameters

accountId

string

Only return feeds assigned to this Pinterest account.

limit

integer

default: 50 >= 1 <= 100

Feeds per page, 1-100. Defaults to 50.

cursor

string

NextCursor from a previous call, to read the next page.

Responses

200

The organization’s feed subscriptions

application/json

object

data

object

feeds

Array<object>

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

pagination

object

limit

required

number

hasMore

required

boolean

nextCursor

Pass as cursor to read the next page. Absent on the last page.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "feeds": [
      {
        "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"
  }
}

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