{
  "openapi": "3.0.3",
  "info": {
    "title": "PageRankCafe API",
    "description": "API for managing ads, credits, and referrals on PageRankCafe. Authenticate with a Bearer token obtained from your account's API Keys page. Errors: every error, including an unknown /api path (404), a malformed JSON body (400) and an unexpected server error (500), is returned as JSON {\"error\": \"message\"} with the matching HTTP status code; check the status code first. Values carry their JSON types: ids, counts and days are integers, ctr is a number, icon and bold are booleans, and dates are strings.",
    "version": "1.2.0",
    "contact": {
      "url": "https://pagerankcafe.com/contact-us"
    }
  },
  "servers": [
    {
      "url": "https://pagerankcafe.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key obtained from your account's API Keys page at /apiKeys"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error response has this body, with the HTTP status code telling the kind of error.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "Not Found",
            "description": "A human-readable message. Errors the API raises on purpose carry their own message; anything else carries the status reason phrase, such as \"Not Found\" or \"Internal Server Error\"."
          }
        }
      },
      "Link": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "views": {
            "type": "integer"
          },
          "link_post_count": {
            "type": "integer"
          }
        }
      },
      "Banner": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Banner image URL (HTTPS, must be a valid image with supported dimensions)"
          },
          "url_target": {
            "type": "string",
            "description": "Click-through destination URL (HTTPS)"
          },
          "impressions": {
            "type": "integer"
          },
          "clicks": {
            "type": "integer"
          },
          "ctr": {
            "type": "number"
          }
        }
      },
      "YouTubeAd": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "video_url": {
            "type": "string",
            "description": "The video's YouTube link (the same value as youtube_link)."
          },
          "views": {
            "type": "integer"
          },
          "youtube_ad_post_count": {
            "type": "integer"
          }
        }
      },
      "PressRelease": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "views": {
            "type": "integer"
          },
          "post_count": {
            "type": "integer"
          }
        }
      },
      "Credits": {
        "type": "object",
        "properties": {
          "available_credits": {
            "type": "integer"
          },
          "available_posts": {
            "type": "integer"
          },
          "links_viewed": {
            "type": "integer"
          },
          "links_remaining": {
            "type": "integer"
          }
        }
      },
      "Referrals": {
        "type": "object",
        "properties": {
          "today": {
            "type": "integer"
          },
          "last_7_days": {
            "type": "integer"
          },
          "last_30_days": {
            "type": "integer"
          },
          "all_time": {
            "type": "integer"
          }
        }
      },
      "LinkPost": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "link_id": {
            "type": "integer"
          },
          "icon": {
            "type": "integer",
            "description": "Icon number: 0 none, 1-19 and 21 picture icons, 20 the member's profile picture"
          },
          "bold": {
            "type": "boolean"
          },
          "view_time": {
            "type": "integer"
          },
          "view_credits": {
            "type": "integer"
          },
          "date_posted": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Post": {
        "type": "object",
        "description": "One row per ad placement. Field set depends on `type`: link (views, view_credits, ad_days, icon, bold, view_time, date_posted), banner (impressions, clicks, ctr, start_date, end_date, days), youtube (impressions, start_date, end_date, days), press_release (views, start_date, end_date, days).",
        "properties": {
          "id": {
            "type": "integer"
          },
          "link_id": {
            "type": "integer",
            "description": "type=link only"
          },
          "banner_id": {
            "type": "integer",
            "description": "type=banner only"
          },
          "youtube_ad_id": {
            "type": "integer",
            "description": "type=youtube only"
          },
          "press_release_id": {
            "type": "integer",
            "description": "type=press_release only"
          },
          "views": {
            "type": "integer",
            "description": "type=link and type=press_release"
          },
          "view_credits": {
            "type": "integer",
            "description": "type=link only"
          },
          "ad_days": {
            "type": "integer",
            "description": "type=link only"
          },
          "icon": {
            "type": "integer",
            "description": "type=link only: icon number (0 none, 1-19 and 21 picture icons, 20 the member's profile picture)"
          },
          "bold": {
            "type": "boolean",
            "description": "type=link only"
          },
          "view_time": {
            "type": "integer",
            "description": "type=link only"
          },
          "date_posted": {
            "type": "string",
            "format": "date-time",
            "description": "type=link only"
          },
          "impressions": {
            "type": "integer",
            "description": "type=banner and type=youtube"
          },
          "clicks": {
            "type": "integer",
            "description": "type=banner only"
          },
          "ctr": {
            "type": "number",
            "description": "type=banner only"
          },
          "start_date": {
            "type": "string",
            "format": "date-time",
            "description": "type=banner, youtube, press_release"
          },
          "end_date": {
            "type": "string",
            "format": "date-time",
            "description": "type=banner, youtube, press_release"
          },
          "days": {
            "type": "integer",
            "description": "type=banner, youtube, press_release"
          }
        }
      },
      "PlatformInsights": {
        "type": "object",
        "properties": {
          "period_days": {
            "type": "integer",
            "example": 30
          },
          "banners": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "Banner size/location, e.g. TOP_BOTTOM, HALF_SIDE"
                },
                "active_placements": {
                  "type": "integer"
                },
                "avg_impressions_per_placement_per_day": {
                  "type": "number"
                },
                "avg_ctr": {
                  "type": "number"
                }
              }
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "icon": {
                  "type": "integer"
                },
                "bold": {
                  "type": "boolean"
                },
                "view_time": {
                  "type": "integer"
                },
                "view_credits": {
                  "type": "integer"
                },
                "active_placements": {
                  "type": "integer"
                },
                "avg_views_per_placement_per_day": {
                  "type": "number"
                }
              }
            }
          },
          "youtube": {
            "type": "object",
            "properties": {
              "active_placements": {
                "type": "integer"
              },
              "avg_impressions_per_placement_per_day": {
                "type": "number"
              }
            }
          },
          "press_releases": {
            "type": "object",
            "properties": {
              "active_placements": {
                "type": "integer"
              },
              "avg_views_per_article_per_day": {
                "type": "number"
              }
            }
          },
          "platform": {
            "type": "object",
            "properties": {
              "daily_views": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string",
                      "format": "date"
                    },
                    "views": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "prices": {
            "type": "object",
            "properties": {
              "post_ratio": {
                "type": "integer",
                "description": "Credits per posted point"
              },
              "banner_price": {
                "type": "number"
              },
              "sticky_price": {
                "type": "number"
              },
              "press_release_price": {
                "type": "number"
              },
              "youtube_ad_price": {
                "type": "number"
              },
              "post_point_price": {
                "type": "number"
              },
              "tiers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "price": {
                      "type": "number"
                    },
                    "discount": {
                      "type": "number"
                    },
                    "multiplier": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Health check",
        "description": "Returns API status and authenticated user info.",
        "tags": [
          "General"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "user": {
                      "type": "string",
                      "example": "johndoe"
                    },
                    "membership": {
                      "type": "string",
                      "enum": [
                        "free",
                        "upgraded"
                      ],
                      "example": "upgraded"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/links": {
      "get": {
        "summary": "List your links",
        "description": "Returns all active, non-reported links for the authenticated user.",
        "tags": [
          "Read"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Link"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/banners": {
      "get": {
        "summary": "List your banners",
        "description": "Returns all active banners for the authenticated user.",
        "tags": [
          "Read"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "banners": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Banner"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/youtube-ads": {
      "get": {
        "summary": "List your YouTube ads",
        "description": "Returns all active, non-reported YouTube ads for the authenticated user.",
        "tags": [
          "Read"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "youtube_ads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/YouTubeAd"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/press-releases": {
      "get": {
        "summary": "List your press releases",
        "description": "Returns all active, non-reported press releases for the authenticated user. Drafts (status 0) are not listed.",
        "tags": [
          "Read"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "press_releases": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PressRelease"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/credits": {
      "get": {
        "summary": "Get credit balance",
        "description": "Returns available credits, posts, links viewed, and links remaining for the authenticated user.",
        "tags": [
          "Read"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "credits": {
                      "$ref": "#/components/schemas/Credits"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/referral-stats": {
      "get": {
        "summary": "Get referral statistics",
        "description": "Returns referral counts for today, last 7 days, last 30 days, and all time.",
        "tags": [
          "Read"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "referrals": {
                      "$ref": "#/components/schemas/Referrals"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/images/upload": {
      "post": {
        "summary": "Upload an image",
        "description": "Uploads an image and returns a hosted HTTPS URL for use elsewhere in the API (e.g. as a banner image URL or an inline press release image). Requires paid membership. Sent as multipart/form-data. Max 2MB; allowed formats JPG, PNG, GIF, WEBP. When type is 'banner' the image must match a supported banner dimension.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "image",
                  "type"
                ],
                "properties": {
                  "image": {
                    "type": "string",
                    "format": "binary",
                    "description": "The image file (max 2MB; JPG, PNG, GIF, WEBP)."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "banner",
                      "article"
                    ],
                    "description": "Image category. 'banner' images must match a supported banner dimension: 728x90, 300x250, 120x600, 160x600, 468x60, 336x280, 250x250, 851x315, 650x400, 800x82, 234x60, 125x125, 300x200, 120x240, 240x400, 150x60"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Image uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "uploaded"
                    },
                    "type": {
                      "type": "string",
                      "example": "banner"
                    },
                    "url": {
                      "type": "string",
                      "example": "https://pagerankcafe-assets.s3.us-west-2.amazonaws.com/banners/123-uuid.png"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/banners/create": {
      "post": {
        "summary": "Create a banner",
        "description": "Creates a new banner ad. Requires paid membership. The banner image URL must be HTTPS and point to an image with supported dimensions. The location is automatically detected from the image size.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "url",
                  "url_target"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Banner title"
                  },
                  "url": {
                    "type": "string",
                    "description": "HTTPS URL to the banner image. Supported sizes: 728x90, 300x250, 120x600, 160x600, 468x60, 336x280, 250x250, 851x315, 650x400, 800x82, 234x60, 125x125, 300x200, 120x240, 240x400, 150x60"
                  },
                  "url_target": {
                    "type": "string",
                    "description": "HTTPS click-through destination URL"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Banner created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "created"
                    },
                    "banner": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "title": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "url_target": {
                          "type": "string"
                        },
                        "location": {
                          "type": "string",
                          "enum": [
                            "TOP_BOTTOM",
                            "HALF",
                            "FULL_SIDE",
                            "HALF_SIDE",
                            "BILLBOARD"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/banners/post": {
      "post": {
        "summary": "Post a banner with credits",
        "description": "Posts an existing banner into rotation using credits. Paid members can post 1-2 day banners (10 credits per day).",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "banner_id"
                ],
                "properties": {
                  "banner_id": {
                    "type": "integer",
                    "description": "ID of the banner to post"
                  },
                  "days": {
                    "type": "integer",
                    "description": "Duration in days. Paid members: 1-2.",
                    "default": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Banner posted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "posted"
                    },
                    "banner_post": {
                      "type": "object",
                      "properties": {
                        "banner_id": {
                          "type": "integer"
                        },
                        "days": {
                          "type": "integer"
                        },
                        "start_date": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "end_date": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or insufficient credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/youtube-ads/create": {
      "post": {
        "summary": "Create a YouTube ad",
        "description": "Creates a new YouTube video ad. Requires paid membership. The video ID is extracted automatically from the youtube_link. Creating with status 1 (the default) emails your followers about the video \u2014 followers are only notified once per video, ever. Pass status 0 to create it silently as Disabled.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "youtube_link"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Video ad title"
                  },
                  "youtube_link": {
                    "type": "string",
                    "description": "YouTube video URL (youtube.com/watch, youtu.be, embed, or /v/ formats)"
                  },
                  "description": {
                    "type": "string",
                    "description": "Optional description"
                  },
                  "status": {
                    "type": "integer",
                    "description": "1 = Active (default; notifies your followers), 0 = Disabled (silent)",
                    "enum": [
                      0,
                      1
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "YouTube ad created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "created"
                    },
                    "youtube_ad": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "title": {
                          "type": "string"
                        },
                        "youtube_video_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/youtube-ads/update": {
      "patch": {
        "summary": "Update a YouTube ad",
        "description": "Updates an existing YouTube video ad. Only the fields supplied are changed; omitted fields keep their current value. You can only update your own ads. Requires paid membership. Uses PATCH: the request is a partial update, not a full replacement.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "youtube_ad_id"
                ],
                "properties": {
                  "youtube_ad_id": {
                    "type": "integer",
                    "description": "ID of the video ad to update (must belong to you)"
                  },
                  "title": {
                    "type": "string",
                    "description": "Ad title"
                  },
                  "description": {
                    "type": "string",
                    "description": "Ad description"
                  },
                  "youtube_link": {
                    "type": "string",
                    "description": "YouTube video URL; the video ID is re-derived from it"
                  },
                  "status": {
                    "type": "integer",
                    "description": "1 = Active, 0 = Disabled. Setting an ad Active emails your followers (once per ad, ever)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "YouTube ad updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "updated"
                    },
                    "youtube_ad": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "title": {
                          "type": "string"
                        },
                        "youtube_video_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "YouTube ad not found or not owned by you",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/press-releases/create": {
      "post": {
        "summary": "Create a press release",
        "description": "Creates a new press release / blog article. Requires paid membership. status is required and has no default: 1 = Active (live and listed at once, and your followers are emailed, once per article ever); 0 = Draft (nobody is emailed and the article is listed nowhere: not on your profile, the blog pages, the home page widgets or GET /api/press-releases; anyone with its exact URL /pressRelease/blog/<slug> can still view it, and that page tells search engines not to index it). Publish a draft with PATCH /api/press-releases/update sending press_release_id and status 1. A missing status, or any value other than the JSON integer 0 or 1, is refused with 400 and nothing is saved. Creating an article does not place it in the home page press release widget; that is POST /api/press-releases/post.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "url",
                  "intro",
                  "body",
                  "slug",
                  "status"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Article title"
                  },
                  "url": {
                    "type": "string",
                    "description": "HTTPS source URL"
                  },
                  "intro": {
                    "type": "string",
                    "description": "Short introduction text"
                  },
                  "body": {
                    "type": "string",
                    "description": "Full article HTML content"
                  },
                  "slug": {
                    "type": "string",
                    "description": "URL slug (must be unique)"
                  },
                  "meta_description": {
                    "type": "string",
                    "description": "SEO meta description (optional)"
                  },
                  "status": {
                    "type": "integer",
                    "enum": [
                      0,
                      1
                    ],
                    "description": "Required, no default. 1 = Active (listed, emails your followers once per article ever); 0 = Draft (unlisted, viewable only by its URL, emails nobody)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Press release created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "created"
                    },
                    "press_release": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "title": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/press-releases/update": {
      "patch": {
        "summary": "Update a press release",
        "description": "Updates an existing press release / blog article. Only the fields supplied are changed; omitted fields keep their current value. You can only update your own articles. Requires paid membership. Uses PATCH: the request is a partial update, not a full replacement. To publish a draft, send only press_release_id and status 1: the article goes live and is listed, and your followers are emailed (the first time it becomes Active; never again after that).",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "press_release_id"
                ],
                "properties": {
                  "press_release_id": {
                    "type": "integer",
                    "description": "ID of the article to update (must belong to you)"
                  },
                  "title": {
                    "type": "string",
                    "description": "Article title"
                  },
                  "url": {
                    "type": "string",
                    "description": "HTTPS source URL"
                  },
                  "intro": {
                    "type": "string",
                    "description": "Short introduction text"
                  },
                  "body": {
                    "type": "string",
                    "description": "Full article HTML content"
                  },
                  "slug": {
                    "type": "string",
                    "description": "URL slug (must be unique)"
                  },
                  "meta_description": {
                    "type": "string",
                    "description": "SEO meta description"
                  },
                  "status": {
                    "type": "integer",
                    "enum": [
                      0,
                      1
                    ],
                    "description": "1 = Active, 0 = Draft (Disabled: unlisted, viewable only by its URL). Setting an article Active emails your followers (once per article, ever). Any other value is refused with 400."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Press release updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "updated"
                    },
                    "press_release": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "title": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Press release not found or not owned by you",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/press-releases/post": {
      "post": {
        "summary": "Post a press release with credits",
        "description": "Places one of your press releases in the home page press release widget for a number of days, paid with credits: paid members post for 7 days at 70 credits (7 post points); admins post for 7, 30, 180 or 365 days at no cost. The placement starts at once. Only an Active article can be posted: a draft (status 0) is refused with 400 {\"error\": \"press release is a draft; publish it (PATCH status 1) before posting\"}, and nothing is charged, placed or queued. Publish the draft first (PATCH /api/press-releases/update with status 1), then post it. Posting also queues the follower email for the article; it is sent only once per article, ever.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "press_release_id"
                ],
                "properties": {
                  "press_release_id": {
                    "type": "integer",
                    "description": "ID of the press release to post"
                  },
                  "days": {
                    "type": "integer",
                    "description": "Duration in days. Paid members: 7.",
                    "default": 7
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Press release posted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "posted"
                    },
                    "press_release_post": {
                      "type": "object",
                      "properties": {
                        "press_release_id": {
                          "type": "integer"
                        },
                        "days": {
                          "type": "integer"
                        },
                        "start_date": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "end_date": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error, insufficient credits, or the press release is a draft",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/links/create": {
      "post": {
        "summary": "Create a link ad",
        "description": "Creates a new link ad, mirroring LinksController::add's validation. Requires a paid membership. Returns the new link's id.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url",
                  "title"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "HTTPS destination URL for the link ad"
                  },
                  "title": {
                    "type": "string",
                    "description": "Link ad title"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "created"
                    },
                    "link": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "title": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/links/post": {
      "post": {
        "summary": "Post a link ad with credits",
        "description": "Posts an existing link ad into rotation using credits, mirroring the web free-post flow (LinkPost::postLink/savePost). Sponsored (paid via PayPal/crypto) posts are not exposed here and stay on the website; ad_days must be 0. view_time and view_credits are derived server-side from icon/bold/double_time (the same schedule the web free-post form uses) and are not accepted as input, since view_credits is the credit reward funded by other members' views. If the posting user needs approval (LinkPost::user_needs_approval, e.g. the user has been reported), the post is created with status -2 and the response reports status \"pending\" with a message that it awaits approval before going live; otherwise the post is active immediately and the response reports status \"active\". Requires a paid membership. Returns the post id, the derived view_time/view_credits, and the caller's remaining credit balance.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "link_id",
                  "ad_days"
                ],
                "properties": {
                  "link_id": {
                    "type": "integer",
                    "description": "ID of the link to post (must belong to the caller)"
                  },
                  "ad_days": {
                    "type": "integer",
                    "description": "Must be 0. Sponsored/paid link placements (ad_days > 0) require PayPal/crypto checkout and are not available via the API.",
                    "example": 0
                  },
                  "icon": {
                    "type": "integer",
                    "description": "Icon shown next to the link: 0 for none, 1-19 or 21 for a picture icon, 20 for your profile picture (only if you have one). Any icon other than 0 adds 3 credits. Any other value, including true/false, is refused with 400.",
                    "enum": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21],
                    "default": 0
                  },
                  "bold": {
                    "type": "boolean",
                    "description": "Bold the link text (+3 credits)",
                    "default": false
                  },
                  "double_time": {
                    "type": "boolean",
                    "description": "Double the ad's view time (view_time 6s -> 12s, +3 credits), matching the web free-post form's \"double view time\" option.",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link posted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "active",
                      "description": "\"active\" if the post is live immediately, \"pending\" if it requires approval first (LinkPost.status -2)."
                    },
                    "link_post": {
                      "$ref": "#/components/schemas/LinkPost"
                    },
                    "remaining_credits": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string",
                      "description": "Present only when status is \"pending\": explains that the post awaits approval before it goes live."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error, insufficient credits, or ad_days != 0",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Link not found or does not belong to the caller",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/posts": {
      "get": {
        "summary": "List ad placement performance",
        "description": "Returns one row per ad placement (post) belonging to the caller, with the performance fields that exist for that ad type.",
        "tags": [
          "Read"
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "link",
                "banner",
                "youtube",
                "press_release"
              ]
            },
            "description": "Ad type to list placements for"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "expired"
              ]
            },
            "description": "Filter placements by status. Omit to return all placements regardless of status."
          }
        ],
        "responses": {
          "200": {
            "description": "Placements for the requested type",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Post"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid type/status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/insights/platform": {
      "get": {
        "summary": "Platform-wide advertising insights",
        "description": "Trailing 30-day aggregates by ad type and option: active placement counts, average impressions/views per placement per day, average CTR, a 30-day daily platform views series, and current prices. Aggregates only \u2014 never per-member or per-item data belonging to other users. Cached for 1 hour. Requires a paid membership.",
        "tags": [
          "Read"
        ],
        "responses": {
          "200": {
            "description": "Platform insights",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "insights": {
                      "$ref": "#/components/schemas/PlatformInsights"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Paid membership required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "General",
      "description": "Health and status endpoints"
    },
    {
      "name": "Read",
      "description": "Read-only endpoints available to all members"
    },
    {
      "name": "Write",
      "description": "Write endpoints requiring paid membership"
    }
  ]
}
