postlake-dev Social Accounts API

openapi: 3.2.0
info:
  title: PostLake Social Accounts 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: Social Accounts
  description: Connect, list, disconnect social accounts
paths:
  /v1/social-accounts/connect:
    post:
      tags:
      - Social Accounts
      summary: Connect social account
      description: Connect a social account to PostLake with supported credentials. X requires the hosted POST /v1/connect-link OAuth flow and always uses PostLake's shared app. External X tokens are not accepted here.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                platform:
                  $ref: '#/components/schemas/Platform'
                profile:
                  type: string
                  description: Optional profile username to attach to
                handle:
                  type: string
                  description: Platform-specific handle
                appPassword:
                  type: string
                  description: Platform-specific password (e.g. for Bluesky)
              required:
              - platform
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  platform:
                    $ref: '#/components/schemas/Platform'
                  handle:
                    type: string
                  profileId:
                    oneOf:
                    - type: string
                    - type: 'null'
                  status:
                    type: string
                required:
                - id
                - platform
                - handle
                - profileId
                - status
        '400':
          description: Invalid input
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Entitlement exceeded
        '502':
          description: Unsupported platform
      operationId: postV1SocialAccountsConnect
      x-operation-id-source: derived
  /v1/social-accounts:
    get:
      tags:
      - Social Accounts
      summary: List social accounts
      description: List connected social accounts. Cursor-paginated.
      parameters:
      - name: profile
        in: query
        description: Filter by profile username
        schema:
          type: string
      - name: limit
        in: query
        description: Page size, 1-100 (default 50).
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: cursor
        in: query
        description: Opaque cursor from the previous response's `nextCursor`.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/SocialAccount'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                    description: Pass this back as `cursor` to fetch the next page. `null` when there are no more results.
                required:
                - accounts
                - nextCursor
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Profile not found
      operationId: getV1SocialAccounts
      x-operation-id-source: derived
  /v1/social-accounts/{id}/disconnect-preview:
    get:
      tags:
      - Social Accounts
      summary: Preview channel disconnect
      description: Read-only, on-demand preview of at most 100 affected scheduled posts. Returns a full-state snapshot. Queued posts, schedules due within 30 seconds, or more than 100 schedules block disconnect. Larger selections must first use bounded bulk destination edits. No polling or historical-post scan is required.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Preview
          content:
            application/json:
              schema:
                type: object
                properties:
                  affectedSchedules:
                    type: integer
                    description: Count, capped at 100. Check hasMore.
                  hasMore:
                    type: boolean
                  snapshot:
                    type: string
                  blocked:
                    type: boolean
                  reason:
                    type: string
                required:
                - affectedSchedules
                - hasMore
                - snapshot
                - blocked
        '404':
          description: Unknown connected account
      operationId: getV1SocialAccountsByIdDisconnectPreview
      x-operation-id-source: derived
  /v1/social-accounts/{id}:
    get:
      tags:
      - Social Accounts
      summary: Retrieve a social account
      description: One connected account by id. Same shape as a row in the list, so anything holding an acc_… can ask about it directly instead of paging the list and filtering.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown connected account
      operationId: getV1SocialAccountsById
      x-operation-id-source: derived
    delete:
      tags:
      - Social Accounts
      summary: Disconnect a social account
      description: Disconnect at the owner's request. Published posts stay untouched. scheduledPosts=keep (default) preserves schedules and stable identity for reconnection. remove removes this destination from scheduled posts; posts with no destinations left become drafts with their content preserved. remove requires expectedSnapshot from disconnect-preview. Confirmation is fenced against full-post edits, new affected schedules and publishing claims in one bounded transaction. Provider revocation is best effort after the guarded local transaction. Maximum 100 schedules; larger selections require bulk destination edits first. No credits are charged.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: scheduledPosts
        in: query
        schema:
          type: string
          enum:
          - keep
          - remove
          default: keep
      - name: expectedSnapshot
        in: query
        schema:
          type: string
        description: Full-state snapshot from disconnect-preview. Required for remove.
      responses:
        '200':
          description: Disconnected
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  disconnected:
                    type: boolean
                  platform:
                    type: string
                  handle:
                    type: string
                  profileId:
                    type: string
                required:
                - id
                - disconnected
                - platform
                - handle
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown connected account
      operationId: deleteV1SocialAccountsById
      x-operation-id-source: derived
  /v1/social-accounts/{id}/targets:
    get:
      tags:
      - Social Accounts
      summary: List social account targets
      description: 'List postable destinations within an account (Pinterest boards, Facebook Pages). This is also how you turn a board id from a post record back into a name: a post stores the id it published to, and this is the lookup.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  targets:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        url:
                          type: string
                          description: A link a person can open. Only present when the platform publishes one we can trust.
                        owner:
                          type: string
                          description: Who owns the destination, where one login reaches several owners.
                        privacy:
                          type: string
                          description: 'The platform''s own word for who can see it, e.g. public, secret, protected. Check this before posting: a secret board accepts the post and shows it to nobody.'
                        description:
                          type: string
                        itemCount:
                          type: integer
                          description: How much is already there, e.g. a Pinterest board's pin count.
                        parent:
                          type: string
                          description: The destination this one sits inside, where a platform has two levels. A Pinterest board section names its board; a top-level destination has none.
                      required:
                      - id
                      - name
                required:
                - targets
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getV1SocialAccountsByIdTargets
      x-operation-id-source: derived
  /v1/social-accounts/{id}/facebook-pages/search:
    get:
      tags:
      - Social Accounts
      summary: Search Facebook Pages for a mention
      description: Resolve an eligible Facebook Page name to the numeric ID needed by platformOptions.facebook.mentionPages. The connected account must be Facebook. If Meta does not permit Page lookup on that connection, the successful response explains that callers need the Page ID instead.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Connected Facebook account ID.
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
        description: At least two characters from the Page name.
      responses:
        '200':
          description: Matching Pages or a lookup warning
          content:
            application/json:
              schema:
                type: object
                properties:
                  pages:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          type: string
                          description: Numeric Facebook Page ID.
                        name:
                          type: string
                        subtitle:
                          type: string
                          description: Page username, when Meta returns one.
                  warning:
                    type: string
                    description: Why no lookup result could be returned, with the Page ID fallback.
                required:
                - pages
        '400':
          description: The account is not Facebook or cannot be used for Page lookup
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown connected account
      operationId: getV1SocialAccountsByIdFacebookPagesSearch
      x-operation-id-source: derived
  /v1/social-accounts/{id}/publish-info:
    get:
      tags:
      - Social Accounts
      summary: Creator-level publish constraints
      description: 'Live constraints for one connected account (TikTok creator_info): available privacy options, whether comments/duet/stitch are allowed, and this creator''s max video duration. Render post UIs from this. 404 for platforms without creator-level constraints.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  platform:
                    $ref: '#/components/schemas/Platform'
                  username:
                    type: string
                  nickname:
                    type: string
                  avatarUrl:
                    type: string
                  privacyOptions:
                    type: array
                    items:
                      type: string
                  commentDisabled:
                    type: boolean
                  duetDisabled:
                    type: boolean
                  stitchDisabled:
                    type: boolean
                  maxVideoDurationSec:
                    type: integer
                required:
                - platform
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown account or no creator-level constraints
      operationId: getV1SocialAccountsByIdPublishInfo
      x-operation-id-source: derived
components:
  schemas:
    SocialAccount:
      type: object
      properties:
        id:
          type: string
        platform:
          $ref: '#/components/schemas/Platform'
        handle:
          type: string
        profileId:
          oneOf:
          - type: string
          - type: 'null'
        status:
          type: string
        avatarUrl:
          oneOf:
          - type: string
          - type: 'null'
        connectVariant:
          type: string
          description: 'Which door this account was connected through, for networks that have more than one. Instagram is the case: `instagram` means Instagram Login, `facebook` means it was connected through a Facebook Page. The two reach genuinely different feature sets, so this decides what the account can do. Absent on networks with a single way in.'
        accountType:
          oneOf:
          - type: string
            enum:
            - BUSINESS
            - MEDIA_CREATOR
            - PERSONAL
          - type: 'null'
          description: Instagram account type when known. Stories support both login routes, subject to Meta account eligibility. Facebook Login Stories require a Business account. Null means the type is unknown; Meta enforces eligibility during publishing.
        discovers:
          type: object
          description: What this ACCOUNT can search, as opposed to GET /v1/platforms/{platform}, which can only speak for the network as a whole. An Instagram connected by Instagram Login cannot search creators or hashtags however the platform-level flags read, so check here before calling a discovery endpoint rather than learning it from an error.
          properties:
            posts:
              type: boolean
            profiles:
              type: boolean
            profilePosts:
              type: boolean
            places:
              type: boolean
            creators:
              type: boolean
              description: 'True only when the connection can reach its creator-discovery product. A true still leaves the network''s own onboarding to be done: Meta refuses the search with `creator_marketplace_not_onboarded` until the brand has accepted the relevant terms.'
          required:
          - posts
          - profiles
          - profilePosts
          - places
          - creators
        requires:
          oneOf:
          - type: string
          - type: 'null'
          description: 'What this network needs before it will publish, in one sentence (media requirements, title and caption limits). Read it before composing: TikTok, Instagram, YouTube and Pinterest all refuse text-only posts. Null when the network accepts anything.'
      required:
      - id
      - platform
      - handle
      - profileId
      - status
      - discovers
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NormalisedError'
      required:
      - error
    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
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: unauthorized
              message: missing or invalid api key
              retryable: false