postlake-dev Connect API

openapi: 3.2.0
info:
  title: PostLake Connect 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: Connect
  description: Hosted connect/manage page links
paths:
  /v1/connect-link:
    post:
      tags:
      - Connect
      summary: Mint connect link
      description: Mint a short-lived link to the hosted connect/manage page. Pass profile to scope the page to one tenant. Pass returnUrl to send the browser back to your app with connect_status after OAuth (the Upload-Post / Ayrshare JWT pattern). Pass platforms to show only those networks. Do not give end users POST /v1/app-link; that mints a 12-hour dashboard session.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: string
                  minLength: 1
                  description: Scope the hosted page and the new connection to this profile username. Required for tenant-safe handoffs; workspace API keys still access all profiles.
                returnUrl:
                  type: string
                  format: uri
                  description: https callback URL without credentials or a fragment. http is allowed only for localhost. Outcome query parameters are unsigned display hints. Bind an expiring single-use state to your signed-in customer on your backend, then read their stored profile's accounts. Never authorize a tenant using the returned profile parameter.
                platforms:
                  type: array
                  minItems: 1
                  items:
                    type: string
                  description: Optional non-empty allow-list enforced on connection and disconnection routes, not just page visibility. Omit for all available networks.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                  expiresInSeconds:
                    type: integer
                required:
                - url
                - expiresInSeconds
        '400':
          description: Invalid return URL, platform allow-list, or request body
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The requested profile does not exist
      operationId: postV1ConnectLink
      x-operation-id-source: derived
  /v1/app-link:
    post:
      tags:
      - Connect
      summary: Mint app link
      description: Mint a session link to the full app dashboard
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                  expiresInSeconds:
                    type: integer
                required:
                - url
                - expiresInSeconds
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: postV1AppLink
      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