cURL Examples

These examples show how to interact with the Tailwind API using cURL from the command line.

Setup

Set your API key as an environment variable:

export TAILWIND_API_KEY="your_api_key_here"

List Accounts

curl -X GET https://api-v1.tailwind.ai/v1/accounts \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

Response:

{
  "data": {
    "accounts": [
      {
        "id": "acc_123456",
        "userId": "987654321",
        "displayName": "My Pinterest",
        "username": "mypinterest",
        "avatarUrl": "https://...",
        "tokenAuthorized": true,
        "isDomainVerified": true,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

List Boards

curl -X GET https://api-v1.tailwind.ai/v1/accounts/acc_123456/boards \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

Response:

{
  "data": {
    "boards": [
      {
        "id": "board_789",
        "name": "Recipe Ideas",
        "isCollaborator": false,
        "isSecret": false
      }
    ]
  },
  "meta": {
    "requestId": "req_def456"
  }
}

List Board Lists

curl -X GET https://api-v1.tailwind.ai/v1/accounts/acc_123456/board-lists \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

List Timeslots

curl -X GET https://api-v1.tailwind.ai/v1/accounts/acc_123456/timeslots \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

Response:

{
  "data": {
    "timeslots": [
      {
        "id": "slot_1",
        "accountId": "acc_123456",
        "dayPreference": 1,
        "timePreference": "09:00",
        "timezone": "America/New_York",
        "type": "optimal",
        "sendAt": 1705755600
      }
    ]
  }
}

Create a Scheduled Post

curl -X POST https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts \
  -H "Authorization: Bearer $TAILWIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaUrl": "https://example.com/my-image.jpg",
    "title": "Amazing Recipe",
    "description": "Try this delicious recipe! #recipes #cooking",
    "url": "https://myblog.com/recipe",
    "boardId": "board_789",
    "altText": "A colorful plate of food",
    "sendAt": "2024-01-20T14:00:00Z"
  }'

Response:

{
  "data": {
    "post": {
      "id": "post_abc123",
      "status": "queued",
      "mediaUrl": "https://example.com/my-image.jpg",
      "mediaType": "image",
      "title": "Amazing Recipe",
      "description": "Try this delicious recipe! #recipes #cooking",
      "url": "https://myblog.com/recipe",
      "boardId": "board_789",
      "altText": "A colorful plate of food",
      "sendAt": 1705758000,
      "sentAt": null,
      "createdAt": 1705320000,
      "pinId": null
    }
  },
  "meta": {
    "requestId": "req_ghi789"
  }
}

Create a Draft Post

Omit the sendAt field to create a draft:

curl -X POST https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts \
  -H "Authorization: Bearer $TAILWIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaUrl": "https://example.com/my-image.jpg",
    "title": "Draft Post",
    "description": "I will schedule this later"
  }'

Schedule a Draft Post

curl -X POST https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts/post_abc123/schedule \
  -H "Authorization: Bearer $TAILWIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sendAt": "2024-01-25T09:00:00Z"
  }'

List Posts

List queued posts (default)

curl -X GET "https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts" \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

List drafts

curl -X GET "https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts?status=draft" \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

List sent posts with date range

curl -X GET "https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts?status=sent&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

List with pagination

curl -X GET "https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts?limit=10" \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

# Use the cursor from the response for the next page
curl -X GET "https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts?limit=10&cursor=abc123" \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

Get a Specific Post

curl -X GET https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts/post_abc123 \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

Delete a Post

curl -X DELETE https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts/post_abc123 \
  -H "Authorization: Bearer $TAILWIND_API_KEY"

Response:

{
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_xyz789"
  }
}

Health Check

curl -X GET https://api-v1.tailwind.ai/health

Response:

{
  "status": "ok"
}

Using jq for Pretty Output

Install jq for formatted JSON output:

# List accounts with formatted output
curl -s -X GET https://api-v1.tailwind.ai/v1/accounts \
  -H "Authorization: Bearer $TAILWIND_API_KEY" | jq

# Extract just the account IDs
curl -s -X GET https://api-v1.tailwind.ai/v1/accounts \
  -H "Authorization: Bearer $TAILWIND_API_KEY" | jq '.data.accounts[].id'

# Get the first account's boards
ACCOUNT_ID=$(curl -s -X GET https://api-v1.tailwind.ai/v1/accounts \
  -H "Authorization: Bearer $TAILWIND_API_KEY" | jq -r '.data.accounts[0].id')

curl -s -X GET "https://api-v1.tailwind.ai/v1/accounts/$ACCOUNT_ID/boards" \
  -H "Authorization: Bearer $TAILWIND_API_KEY" | jq

Shell Script Example

#!/bin/bash
# schedule-post.sh - Schedule a pin to Pinterest via Tailwind API

set -e

API_URL="https://api-v1.tailwind.ai"
ACCOUNT_ID="acc_123456"
BOARD_ID="board_789"

# Check for required environment variable
if [ -z "$TAILWIND_API_KEY" ]; then
    echo "Error: TAILWIND_API_KEY environment variable is not set"
    exit 1
fi

# Parse arguments
IMAGE_URL="$1"
TITLE="$2"
DESCRIPTION="$3"
SCHEDULE_TIME="$4"

if [ -z "$IMAGE_URL" ] || [ -z "$TITLE" ]; then
    echo "Usage: $0 <image_url> <title> [description] [schedule_time]"
    echo "  schedule_time: ISO 8601 format (e.g., 2024-01-20T14:00:00Z)"
    exit 1
fi

# Build JSON payload
JSON_PAYLOAD=$(jq -n \
    --arg mediaUrl "$IMAGE_URL" \
    --arg title "$TITLE" \
    --arg description "${DESCRIPTION:-}" \
    --arg boardId "$BOARD_ID" \
    --arg sendAt "${SCHEDULE_TIME:-}" \
    '{
        mediaUrl: $mediaUrl,
        title: $title,
        boardId: $boardId
    }
    + (if $description != "" then {description: $description} else {} end)
    + (if $sendAt != "" then {sendAt: $sendAt} else {} end)')

# Create the post
RESPONSE=$(curl -s -X POST "$API_URL/v1/accounts/$ACCOUNT_ID/posts" \
    -H "Authorization: Bearer $TAILWIND_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD")

# Check for errors
if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then
    echo "Error: $(echo "$RESPONSE" | jq -r '.error.message')"
    exit 1
fi

# Success
POST_ID=$(echo "$RESPONSE" | jq -r '.data.post.id')
STATUS=$(echo "$RESPONSE" | jq -r '.data.post.status')

echo "Post created successfully!"
echo "  ID: $POST_ID"
echo "  Status: $STATUS"

if [ -n "$SCHEDULE_TIME" ]; then
    echo "  Scheduled for: $SCHEDULE_TIME"
fi

Usage:

chmod +x schedule-post.sh

# Create a draft
./schedule-post.sh "https://example.com/image.jpg" "My Pin Title"

# Create with description
./schedule-post.sh "https://example.com/image.jpg" "My Pin Title" "Check out this amazing content!"

# Schedule for a specific time
./schedule-post.sh "https://example.com/image.jpg" "My Pin Title" "Description here" "2024-01-20T14:00:00Z"

Error Responses

401 Unauthorized

curl -s -X GET https://api-v1.tailwind.ai/v1/accounts \
  -H "Authorization: Bearer invalid_key" | jq

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

429 Rate Limited

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

404 Not Found

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