{
  "info": {
    "name": "SocialRails Public API",
    "description": "Complete collection for the SocialRails Public API v1.\n\nSet the `api_key` variable to your API key (from Dashboard > Settings > API).\n\nDocs: https://socialrails.com/documentation/api-overview",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      { "key": "token", "value": "{{api_key}}", "type": "string" }
    ]
  },
  "variable": [
    { "key": "base_url", "value": "https://socialrails.com/api/v1" },
    { "key": "api_key", "value": "sr_live_YOUR_KEY_HERE" },
    { "key": "post_id", "value": "POST_UUID_HERE" },
    { "key": "account_id", "value": "ACCOUNT_UUID_HERE" },
    { "key": "webhook_id", "value": "WEBHOOK_UUID_HERE" },
    { "key": "media_key", "value": "MEDIA_KEY_HERE" }
  ],
  "item": [
    {
      "name": "Health",
      "item": [
        {
          "name": "Health check",
          "request": {
            "auth": { "type": "noauth" },
            "method": "GET",
            "url": { "raw": "{{base_url}}/health", "host": ["{{base_url}}"], "path": ["health"] },
            "description": "Public endpoint — no auth required. Verify the API is reachable."
          }
        }
      ]
    },
    {
      "name": "Posts",
      "item": [
        {
          "name": "List posts",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/posts?status=scheduled&limit=10",
              "host": ["{{base_url}}"],
              "path": ["posts"],
              "query": [
                { "key": "status", "value": "scheduled", "description": "Filter: scheduled, published, draft, failed" },
                { "key": "limit", "value": "10", "description": "Results per page (1-100)" },
                { "key": "offset", "value": "0", "description": "Pagination offset", "disabled": true },
                { "key": "sort", "value": "created_at", "description": "Sort: created_at or scheduled_for", "disabled": true },
                { "key": "platform", "value": "twitter", "description": "Filter by platform", "disabled": true },
                { "key": "from", "value": "2026-01-01T00:00:00Z", "description": "Posts after this date", "disabled": true },
                { "key": "to", "value": "2026-12-31T23:59:59Z", "description": "Posts before this date", "disabled": true }
              ]
            },
            "description": "List posts in your workspace. Requires `read` scope."
          }
        },
        {
          "name": "Get a post",
          "request": {
            "method": "GET",
            "url": { "raw": "{{base_url}}/posts/{{post_id}}", "host": ["{{base_url}}"], "path": ["posts", "{{post_id}}"] },
            "description": "Get a single post by ID. Requires `read` scope."
          }
        },
        {
          "name": "Create a post",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/posts", "host": ["{{base_url}}"], "path": ["posts"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"content\": \"Excited to announce our new feature!\",\n  \"platform\": \"twitter\",\n  \"scheduled_for\": \"2026-03-10T14:00:00Z\"\n}"
            },
            "description": "Create a new post. Requires `write` scope.\n\nPlatform settings are automatically loaded from your workspace defaults."
          }
        },
        {
          "name": "Create a post with media",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/posts", "host": ["{{base_url}}"], "path": ["posts"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"content\": \"Check out this photo!\",\n  \"platform\": \"instagram\",\n  \"media\": [\"{{media_key}}\"],\n  \"scheduled_for\": \"2026-03-10T14:00:00Z\"\n}"
            },
            "description": "Create a post with media attached. Upload media first via /media/upload, then use the `key` from the response."
          }
        },
        {
          "name": "Update a post",
          "request": {
            "method": "PATCH",
            "url": { "raw": "{{base_url}}/posts/{{post_id}}", "host": ["{{base_url}}"], "path": ["posts", "{{post_id}}"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"content\": \"Updated content here\",\n  \"scheduled_for\": \"2026-03-11T10:00:00Z\"\n}"
            },
            "description": "Update a draft or scheduled post. Requires `write` scope."
          }
        },
        {
          "name": "Delete a post",
          "request": {
            "method": "DELETE",
            "url": { "raw": "{{base_url}}/posts/{{post_id}}", "host": ["{{base_url}}"], "path": ["posts", "{{post_id}}"] },
            "description": "Delete a draft or scheduled post. Published/failed posts cannot be deleted. Requires `write` scope."
          }
        },
        {
          "name": "Create a thread",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/posts", "host": ["{{base_url}}"], "path": ["posts"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"content\": \"Thread start\",\n  \"platform\": \"twitter\",\n  \"scheduled_for\": \"2026-03-15T14:00:00Z\",\n  \"thread\": [\n    \"1/ Why we built SocialRails — a thread\",\n    \"2/ Managing 9 social platforms is chaos\",\n    \"3/ We built one API to schedule everywhere\",\n    \"4/ Try it free at socialrails.com\"\n  ],\n  \"thread_delay\": 1\n}"
            },
            "description": "Create a multi-tweet thread. The `thread` array contains 2-25 items. Supported on twitter and threads. Use `thread_media` to attach media per item and `thread_delay` (0-60 min) to space items. Requires `write` scope."
          }
        },
        {
          "name": "Batch create posts",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/posts/batch", "host": ["{{base_url}}"], "path": ["posts", "batch"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"content\": \"Big announcement coming soon!\",\n  \"platforms\": [\"twitter\", \"linkedin\", \"facebook\"],\n  \"scheduled_for\": \"2026-03-10T14:00:00Z\",\n  \"platform_content\": {\n    \"twitter\": \"Short tweet version!\"\n  }\n}"
            },
            "description": "Post to multiple platforms at once. Each platform counts as one post. Requires `write` scope."
          }
        }
      ]
    },
    {
      "name": "Analytics",
      "item": [
        {
          "name": "Get analytics",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/analytics?period=30d",
              "host": ["{{base_url}}"],
              "path": ["analytics"],
              "query": [
                { "key": "period", "value": "30d", "description": "7d, 30d, 90d, or 365d" },
                { "key": "platform", "value": "twitter", "description": "Filter by platform", "disabled": true },
                { "key": "post_id", "value": "", "description": "Analytics for a specific post", "disabled": true }
              ]
            },
            "description": "Get posting analytics for your workspace. Requires `read` scope."
          }
        }
      ]
    },
    {
      "name": "Accounts",
      "item": [
        {
          "name": "List accounts",
          "request": {
            "method": "GET",
            "url": { "raw": "{{base_url}}/accounts", "host": ["{{base_url}}"], "path": ["accounts"] },
            "description": "List connected social media accounts. Never exposes tokens. Requires `read` scope."
          }
        },
        {
          "name": "Get account settings",
          "request": {
            "method": "GET",
            "url": { "raw": "{{base_url}}/accounts/{{account_id}}/settings", "host": ["{{base_url}}"], "path": ["accounts", "{{account_id}}", "settings"] },
            "description": "Get platform capabilities, default settings, and available tools for a connected account. Requires `read` scope."
          }
        },
        {
          "name": "Trigger account tool",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/accounts/{{account_id}}/tools", "host": ["{{base_url}}"], "path": ["accounts", "{{account_id}}", "tools"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"tool\": \"pages\"\n}"
            },
            "description": "Trigger a platform discovery tool. Available tools vary by platform: pages (facebook), boards (pinterest), companies (linkedin), communities (twitter). Requires `read` scope."
          }
        }
      ]
    },
    {
      "name": "AI Generation",
      "item": [
        {
          "name": "Generate content",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/ai/generate", "host": ["{{base_url}}"], "path": ["ai", "generate"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"prompt\": \"Write a tweet announcing our summer sale with 30% off all products\",\n  \"platform\": \"twitter\",\n  \"tone\": \"humorous\"\n}"
            },
            "description": "Generate AI-powered social media content. Deducts 2 AI credits. Requires `ai` scope."
          }
        }
      ]
    },
    {
      "name": "Workspace",
      "item": [
        {
          "name": "Get workspace info",
          "request": {
            "method": "GET",
            "url": { "raw": "{{base_url}}/workspace", "host": ["{{base_url}}"], "path": ["workspace"] },
            "description": "Get workspace info, plan limits, and current usage. Requires `read` scope."
          }
        }
      ]
    },
    {
      "name": "Media",
      "item": [
        {
          "name": "Upload a file",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/media/upload", "host": ["{{base_url}}"], "path": ["media", "upload"] },
            "body": {
              "mode": "formdata",
              "formdata": [
                { "key": "file", "type": "file", "description": "Image (JPEG, PNG, GIF, WebP) or video (MP4), max 10MB" },
                { "key": "type", "value": "image", "type": "text", "description": "image, video, or thumbnail", "disabled": true }
              ]
            },
            "description": "Upload a file via multipart form data. Use the `key` from the response in the `media` array when creating posts. Set type=thumbnail for video cover images."
          }
        },
        {
          "name": "Upload from URL",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/media/upload-url", "host": ["{{base_url}}"], "path": ["media", "upload-url"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://example.com/my-image.png\"\n}"
            },
            "description": "Fetch and store media from a URL. Requires `write` scope."
          }
        }
      ]
    },
    {
      "name": "Webhooks",
      "item": [
        {
          "name": "List webhooks",
          "request": {
            "method": "GET",
            "url": { "raw": "{{base_url}}/webhooks", "host": ["{{base_url}}"], "path": ["webhooks"] },
            "description": "List registered webhooks. Requires `read` scope."
          }
        },
        {
          "name": "Register a webhook",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/webhooks", "host": ["{{base_url}}"], "path": ["webhooks"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://your-app.com/webhooks/socialrails\",\n  \"events\": [\"post.published\", \"post.failed\"]\n}"
            },
            "description": "Register a new webhook. Save the `secret` from the response — it's only shown once. Requires `webhooks` scope."
          }
        },
        {
          "name": "Delete a webhook",
          "request": {
            "method": "DELETE",
            "url": { "raw": "{{base_url}}/webhooks/{{webhook_id}}", "host": ["{{base_url}}"], "path": ["webhooks", "{{webhook_id}}"] },
            "description": "Remove a webhook registration. Requires `webhooks` scope."
          }
        }
      ]
    },
    {
      "name": "Workflows",
      "description": "Common multi-step workflows demonstrating real-world API usage.",
      "item": [
        {
          "name": "1. Verify API key",
          "request": {
            "method": "GET",
            "url": { "raw": "{{base_url}}/workspace", "host": ["{{base_url}}"], "path": ["workspace"] },
            "description": "Step 1 of any workflow: verify your API key works by checking workspace info."
          }
        },
        {
          "name": "2. Generate AI content",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/ai/generate", "host": ["{{base_url}}"], "path": ["ai", "generate"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"prompt\": \"Write a motivational Monday post for a tech startup\",\n  \"platform\": \"twitter\",\n  \"tone\": \"inspirational\"\n}"
            },
            "description": "Step 2: Generate content with AI. Copy the generated text for step 3."
          }
        },
        {
          "name": "3. Schedule the generated post",
          "request": {
            "method": "POST",
            "url": { "raw": "{{base_url}}/posts", "host": ["{{base_url}}"], "path": ["posts"] },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"content\": \"PASTE_GENERATED_CONTENT_HERE\",\n  \"platform\": \"twitter\",\n  \"scheduled_for\": \"2026-03-10T08:00:00Z\"\n}"
            },
            "description": "Step 3: Schedule the AI-generated content. Replace the content with the output from step 2."
          }
        },
        {
          "name": "4. Verify it was scheduled",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/posts?status=scheduled&limit=5",
              "host": ["{{base_url}}"],
              "path": ["posts"],
              "query": [
                { "key": "status", "value": "scheduled" },
                { "key": "limit", "value": "5" }
              ]
            },
            "description": "Step 4: Confirm your post shows up in the scheduled posts list."
          }
        }
      ]
    }
  ]
}