postlake-dev Platforms API

openapi: 3.2.0
info:
  title: PostLake Platforms API
  version: 1.0.0
  description: Unified social media API. One API key, 10 platforms, normalised responses. Built for agents and developers.
  contact:
    url: https://postlake.dev
servers:
- url: https://api.postlake.dev
security:
- bearerAuth: []
tags:
- name: Platforms
  description: Machine-readable platform capabilities (public)
paths:
  /v1/platforms:
    get:
      tags:
      - Platforms
      summary: Platform capabilities (public)
      description: 'Machine-readable capabilities per platform: character limits, media rules (required / video-only / max images / formats / sizes), whether publishing is asynchronous, and every platformOptions field with its valid values. No authentication required.'
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  platforms:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformCapabilities'
                required:
                - platforms
      operationId: getV1Platforms
      x-operation-id-source: derived
  /v1/platforms/{platform}:
    get:
      tags:
      - Platforms
      summary: One platform's capabilities (public)
      security: []
      parameters:
      - name: platform
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformCapabilities'
        '404':
          description: Unknown platform
      operationId: getV1PlatformsByPlatform
      x-operation-id-source: derived
components:
  schemas:
    PlatformCapabilities:
      type: object
      description: 'What one platform supports: limits, media rules, and every platformOptions field with its valid values.'
      properties:
        platform:
          $ref: '#/components/schemas/Platform'
        displayName:
          type: string
        connectionAvailability:
          type: object
          description: Public rollout status and connection eligibility for the authenticated account. Capability support and rollout availability are separate. Buying credits or a plan does not grant rollout access.
          properties:
            status:
              type: string
              enum:
              - public
              - limited
            reason:
              type:
              - string
              - 'null'
              enum:
              - provider_app_review
              - not_publicly_available
              - null
            accountCanConnect:
              type: boolean
            purchaseUnlocksAccess:
              type: boolean
              const: false
          required:
          - status
          - reason
          - accountCanConnect
          - purchaseUnlocksAccess
        maxChars:
          type: integer
        charsByPostType:
          type: object
          properties:
            video:
              type: integer
            image:
              type: integer
        title:
          type: object
          properties:
            maxChars:
              type: integer
            appliesTo:
              type: string
        media:
          type: object
          properties:
            required:
              type: boolean
            videoRequired:
              type: boolean
            maxImages:
              type: integer
            maxVideos:
              type: integer
            imageTypes:
              type: array
              items:
                type: string
            videoTypes:
              type: array
              items:
                type: string
            maxImageBytes:
              type: integer
            maxVideoBytes:
              type: integer
            maxVideoSeconds:
              type: integer
        postsPerDay:
          type: integer
        postsPerDayScope:
          type: string
          enum:
          - account
          - app
          description: account is that connected social user. app is the whole PostLake project (YouTube uploads).
        asyncPublish:
          type: boolean
        options:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              type:
                type: string
                enum:
                - string
                - boolean
                - enum
                - number
              label:
                type: string
              values:
                type: array
                items:
                  type: string
              default: {}
              appliesTo:
                type: string
              maxLength:
                type: integer
              description:
                type: string
            required:
            - id
            - type
            - label
        notes:
          type: array
          items:
            type: string
        pendingReview:
          type: object
          additionalProperties:
            type: string
          description: Capabilities that are built and tested but waiting on a platform permission. Keyed like the flags (reads.comments, messages). Absent or empty when nothing is waiting.
        firstComment:
          type: boolean
          description: A comment can be posted under the post in the same call.
        deletePost:
          type: boolean
          description: A published post can be retracted through the API.
        thread:
          type: boolean
          description: A chain of posts can be published as one.
        replyToComment:
          type: boolean
        hideComments:
          type: boolean
          description: A reply on your own post can be hidden and unhidden.
        editProfile:
          type: boolean
        messages:
          type: boolean
          description: Direct messages can be read and sent.
        engages:
          type: array
          description: Which actions POST /v1/engagements accepts on this network.
          items:
            type: string
            enum:
            - like
            - unlike
            - repost
            - unrepost
            - follow
            - unfollow
            - block
            - unblock
            - mute
            - unmute
        reads:
          type: object
          description: Which of your own surfaces can be read.
          properties:
            notifications:
              type: boolean
            comments:
              type: boolean
            followers:
              type: boolean
            following:
              type: boolean
        discovers:
          type: object
          description: Which parts of the public network can be searched, so an agent can look before it speaks.
          properties:
            posts:
              type: boolean
            profiles:
              type: boolean
            profilePosts:
              type: boolean
            places:
              type: boolean
            creators:
              type: boolean
              description: Find creators through the network's creator marketplace.
        variants:
          type: array
          description: 'Where a network can be connected in more than one way, the ways it offers. What a connection can do depends on HOW it was made, not only on which network it is: an Instagram account connected through Facebook can search, look people up and read insights, while the same account connected directly cannot. Absent when a network has only one way in.'
          items:
            type: object
            properties:
              id:
                type: string
                description: Pass as `variant` when creating a connect link.
              label:
                type: string
                description: What to call this choice to a person.
              requires:
                type: array
                items:
                  type: string
                description: What the person must already have for this way to work.
              then:
                type: string
                description: What happens next when they choose it.
              summary:
                type: string
                description: What this way of connecting can do, in one line.
              available:
                type: array
                items:
                  type: string
                description: Features available through this connection, suitable for a user-facing comparison.
              unavailable:
                type: array
                items:
                  type: string
                description: Features unavailable through this connection.
              conditions:
                type: array
                items:
                  type: string
                description: Optional account setup the user can complete to enable specific features.
              only:
                type: array
                items:
                  type: string
                description: Capabilities this way unlocks that the others do not.
              note:
                type: string
            required:
            - id
            - label
      required:
      - platform
      - displayName
      - maxChars
      - media
      - options
    Platform:
      type: string
      enum:
      - bluesky
      - threads
      - x
      - linkedin
      - instagram
      - tiktok
      - facebook
      - youtube
      - pinterest