postlake-dev MCP API

openapi: 3.2.0
info:
  title: PostLake MCP 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: MCP
  description: Model Context Protocol JSON-RPC endpoint
paths:
  /v1/mcp:
    post:
      tags:
      - MCP
      summary: MCP Endpoint
      description: 'Model Context Protocol JSON-RPC endpoint. PREFER `POST /mcp`: it is the canonical URL and now accepts either an API key or an OAuth access token, so there is no longer a reason to choose between two paths. This one is kept working for configs already pointing at it. The same tool registry covers publishing, scheduling, validation, media, notifications, comments, direct messages, engagement, profile and channel management, and analytics. See https://docs.postlake.dev/mcp for the full toolset and authentication options.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  const: '2.0'
                method:
                  type: string
                params:
                  type: object
                id:
                  oneOf:
                  - type: string
                  - type: number
                  - type: 'null'
              required:
              - jsonrpc
              - method
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                    const: '2.0'
                  result:
                    type: object
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                    required:
                    - code
                    - message
                  id:
                    oneOf:
                    - type: string
                    - type: number
                    - type: 'null'
                required:
                - jsonrpc
        '204':
          description: Notification success
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: postV1Mcp
      x-operation-id-source: derived
components:
  schemas:
    NormalisedError:
      type: object
      description: '`type` is the coarse category you route on and is deliberately small, so it cannot say WHICH input was wrong. `code`, `fix`, `docs` and `param` are what turn a rejection into something a caller can act on rather than guess at. They are optional only in the sense that not every error has all four.'
      properties:
        type:
          type: string
          description: Coarse category to route on, e.g. rate_limited, auth_expired, platform_rejected.
        message:
          type: string
        platform:
          oneOf:
          - $ref: '#/components/schemas/Platform'
          - type: 'null'
        retryable:
          type: boolean
        code:
          type: string
          description: Stable, granular handle to branch on, e.g. text_too_long. Also the anchor in the error reference.
        fix:
          type: string
          description: The next action, in plain words. Safe to show a person as-is.
        docs:
          type: string
          format: uri
          description: Where the rule is written down, so it is learned once rather than rediscovered.
        param:
          type: string
          description: The request field at fault, so a form can mark the right input.
      required:
      - type
      - message
      - retryable
    Platform:
      type: string
      enum:
      - bluesky
      - threads
      - x
      - linkedin
      - instagram
      - tiktok
      - facebook
      - youtube
      - pinterest
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NormalisedError'
      required:
      - error
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: unauthorized
              message: missing or invalid api key
              retryable: false