Preview a feed before connecting it

POST

/v1/feeds/preview

curl --request POST \
  --url https://api-v1.tailwind.ai/v1/feeds/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "example" }'

• Production
• Development

Resolve a site or feed URL and report what would be subscribed to. Accepts a plain website URL and discovers its feed.

Returns kind: "feed" with a bounded sample of current entries when there is one answer, or kind: "candidates" when a site exposes several feeds — pick one and pass it as feedUrl to connect-feed. Nothing is saved and no credits are spent.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

url

required

A feed URL, or a website URL whose feed should be discovered.

string

<= 2048 characters

Example^generated

{
  "url": "example"
}

Responses

200

The resolved feed, or the candidates to choose between

Media typeapplication/json

object

data

One of:

object

A single resolved feed.

object

kind

required

string

Allowed values: feed

feedUrl

required

Pass this to connect-feed.

string

hostname

required

string

title

required

string

nullable

totalPages

required

Entries currently in the feed. All of them form the baseline on connect; none generate Pins.

number

sectionCount

How many sections the feed has in total, before the list below is capped.

number

sections

required

How the feed’s entries group by URL path. Capped at 25; sectionCount has the true total.

Array<object>

object

name

string

pageCount

number

sampleEntries

required

Up to 10 entries, enough to confirm this is the right feed. Not the full list — totalPages has the count.

Array<object>

object

url

string

title

string

nullable

publishedAt

ISO 8601

string

nullable

object

Several feeds were found; choose one.

object

kind

required

string

Allowed values: candidates

feeds

required

Array<object>

object

feedUrl

string

title

string

nullable

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "kind": "feed"
  }
}

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

404

Resource not found

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": "NOT_FOUND",
    "message": "Account not found"
  },
  "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.

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": "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.

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": "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.

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

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

504

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

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": "GATEWAY_TIMEOUT",
    "message": "The site took too long to respond. Please try again."
  },
  "meta": {
    "requestId": "abc123"
  }
}