postproxy-dev Calendar API

openapi: 3.2.0
info:
  title: Postproxy Social Media Calendar API
  version: '2026-09-21'
  summary: Unified social media API for publishing, comments, direct messages, and reviews.
  description: 'The Postproxy API lets you programmatically create and manage social media posts across Facebook, Instagram, TikTok, LinkedIn, YouTube, X (Twitter), Threads, Pinterest, Bluesky, Telegram, and Google Business. Beyond publishing you can read and reply to comments, read and send direct messages, and reply to Google Business reviews and Facebook Page recommendations.


    Send one payload; Postproxy maps it to each platform''s rules and returns a per-platform outcome. Sandbox mode is included on all plans for development without real accounts.


    Human-readable reference: https://postproxy.dev/reference/overview/


    ## Versioning and deprecation


    The API has a single stable version served at https://api.postproxy.dev/api. Releases are identified by this document''s date-based `info.version`. Changes are additive: new endpoints, new optional parameters, and new response fields may appear, and clients should ignore fields they do not recognize. Existing fields, parameters, and status codes are not changed or removed without a deprecation cycle.


    When an endpoint or field is deprecated it is marked `deprecated: true` in this specification and announced in the changelog (https://postproxy.dev/getting-started/changelog/) at least 90 days before removal.'
  termsOfService: https://postproxy.dev/terms-conditions/
  contact:
    name: Postproxy Support
    url: https://postproxy.dev/developers/
    email: support@postproxy.dev
  x-versioning:
    strategy: stable-single-version
    spec-version-format: date (YYYY-MM-DD)
    compatibility: additive-only; breaking changes go through a deprecation cycle
    deprecation-signal: 'deprecated: true in this spec, plus a changelog announcement at least 90 days before removal'
    changelog: https://postproxy.dev/getting-started/changelog/
servers:
- url: https://api.postproxy.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: Calendar
  description: Public scheduled-posts calendar
  externalDocs:
    url: https://postproxy.dev/reference/calendar/
paths:
  /api/calendar:
    get:
      operationId: calendar_list
      summary: List calendar events
      description: Retrieves a filtered, paginated list of social media calendar events for 2026 — public holidays, awareness days, cultural events, commerce dates, and sensitive/no-post dates. This is a public endpoint; no authentication required.
      tags:
      - Calendar
      externalDocs:
        url: https://postproxy.dev/reference/calendar/
      parameters:
      - name: category
        in: query
        required: false
        description: 'Filter by category. Comma-separated. Values: post_trigger, sensitive, no_post'
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: 'Filter by event type. Comma-separated. Values: public_holiday, fun_holiday, awareness_day, cultural_event, sporting_event, commerce_event, religious_event, seasonal, remembrance'
        schema:
          type: string
      - name: country
        in: query
        required: false
        description: Filter by country code (ISO 3166-1 alpha-2). Comma-separated. Also includes global events
        schema:
          type: string
      - name: tag
        in: query
        required: false
        description: 'Filter by tag. Comma-separated. Examples: sports, food, pets, commerce, environment'
        schema:
          type: string
      - name: month
        in: query
        required: false
        description: Filter by month (1-12)
        schema:
          type: integer
          minimum: 1
          maximum: 12
      - name: q
        in: query
        required: false
        description: Search event names (case-insensitive)
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: Start of date range (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: to
        in: query
        required: false
        description: End of date range (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - $ref: '#/components/parameters/Page'
      - name: per_page
        in: query
        required: false
        description: Results per page (1-100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Paginated list of calendar events
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of events matching the filters
                  page:
                    type: integer
                    description: Current page number
                  per_page:
                    type: integer
                    description: Number of results per page
                  filters:
                    type: object
                    description: Echo of active filters applied to the request
                    additionalProperties: true
                  data:
                    type: array
                    description: Array of event objects
                    items:
                      $ref: '#/components/schemas/CalendarEvent'
components:
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: Page number (1-based). Passing 0 returns page 1.
      schema:
        type: integer
        default: 1
        minimum: 0
  schemas:
    CalendarEvent:
      type: object
      description: A social media calendar event for 2026.
      properties:
        date:
          type: string
          format: date
          description: Event date (YYYY-MM-DD)
        name:
          type: string
          description: Event name
        type:
          type: string
          description: Event type
          enum:
          - public_holiday
          - fun_holiday
          - awareness_day
          - cultural_event
          - sporting_event
          - commerce_event
          - religious_event
          - seasonal
          - remembrance
        category:
          type: string
          description: 'post_trigger: good opportunity to post; sensitive: post with care; no_post: brands should stay silent or share only respectful acknowledgment'
          enum:
          - post_trigger
          - sensitive
          - no_post
        countries:
          type:
          - array
          - 'null'
          description: Country codes (ISO 3166-1 alpha-2) where applicable, or null for global events
          items:
            type: string
        tags:
          type: array
          description: Descriptive tags for filtering
          items:
            type: string
        posting_tip:
          type:
          - string
          - 'null'
          description: Optional social media posting guidance
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key sent as a Bearer token in the Authorization header. Keys are either full-access (entire account) or scoped to a single profile group. Create keys at https://app.postproxy.dev under Settings → API Keys.
externalDocs:
  description: Full API reference
  url: https://postproxy.dev/reference/overview/