postlake-dev Messages API

openapi: 3.2.0
info:
  title: PostLake Messages 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: Messages
  description: Direct message threads
paths:
  /v1/conversations:
    get:
      tags:
      - Messages
      summary: Direct message threads
      parameters:
      - name: account
        in: query
        required: false
        schema:
          type: string
        description: One connected account id (acc_…). Omit for every connected network.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Opaque cursor from a previous page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: 1-100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
                  cursor:
                    type: string
                    nullable: true
                    description: 'Opaque. Pass it back verbatim for the next page; null means the end. Never parse it: on cross-network reads it encodes a position per network.'
                  problems:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReadProblem'
      operationId: getV1Conversations
      x-operation-id-source: derived
    post:
      tags:
      - Messages
      summary: Open a conversation with someone
      description: Finds or starts the thread with a handle, so a first message does not need an id that does not exist yet. Sends nothing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              - handle
              properties:
                account:
                  type: string
                handle:
                  type: string
                  description: e.g. alice.bsky.social
      responses:
        '200':
          description: The conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
      operationId: postV1Conversations
      x-operation-id-source: derived
  /v1/conversations/{id}/messages:
    get:
      tags:
      - Messages
      summary: Messages in one thread
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: account
        in: query
        required: true
        schema:
          type: string
        description: 'Required: a conversation id only means something on one connection'
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Opaque cursor from a previous page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: 1-100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
                  cursor:
                    type: string
                    nullable: true
      operationId: getV1ConversationsByIdMessages
      x-operation-id-source: derived
    post:
      tags:
      - Messages
      summary: Send a direct message
      description: Free on supported networks except X, where sending a direct message costs 6 credits.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              - text
              properties:
                account:
                  type: string
                text:
                  type: string
                humanAgent:
                  type: boolean
                  description: 'Assert that a PERSON wrote this reply. Meta allows a reply within 24 hours of someone''s last message; the Human Agent tag extends that to 7 days and is granted only for replies a human composed. Never set it for an automated reply: the account carries the penalty, not the caller.'
      responses:
        '200':
          description: Sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      operationId: postV1ConversationsByIdMessages
      x-operation-id-source: derived
  /v1/conversations/{id}/read:
    post:
      tags:
      - Messages
      summary: Mark a conversation read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              properties:
                account:
                  type: string
      responses:
        '200':
          description: Success
      operationId: postV1ConversationsByIdRead
      x-operation-id-source: derived
components:
  schemas:
    ReadProblem:
      type: object
      description: A network that could not be read for this request. Its presence is what lets you tell 'nothing happened' from 'we could not look'.
      properties:
        account:
          type: string
        platform:
          type: string
        reason:
          type: string
    Message:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        createdAt:
          type: string
          format: date-time
        from:
          $ref: '#/components/schemas/SocialActor'
        fromMe:
          type: boolean
          description: True when you sent it, so callers never compare handles
        content:
          $ref: '#/components/schemas/MessageContent'
    Conversation:
      type: object
      description: A direct-message thread. inboxAccount names the connected profile receiving messages and sending replies, so callers never infer it from account.
      properties:
        id:
          type: string
        platform:
          type: string
        account:
          type: string
        inboxAccount:
          allOf:
          - $ref: '#/components/schemas/InboxAccountIdentity'
          nullable: true
        participants:
          type: array
          items:
            $ref: '#/components/schemas/SocialActor'
        lastMessage:
          type: object
          nullable: true
          properties:
            text:
              type: string
            createdAt:
              type: string
              format: date-time
            fromMe:
              type: boolean
            content:
              $ref: '#/components/schemas/MessageContent'
        unreadCount:
          type: integer
    SocialActor:
      type: object
      properties:
        handle:
          type: string
        displayName:
          type: string
          nullable: true
        avatarUrl:
          type: string
          nullable: true
        id:
          type: string
          nullable: true
          description: The network's own id, for follow/block/mute
    MessageContent:
      type: object
      description: A meaningful non-text direct-message payload. This is present for attachments, shared media, and message types the network does not expose in readable form. Do not treat an empty text field with this object as an empty message.
      properties:
        kind:
          type: string
          enum:
          - attachment
          - shared_media
          - unsupported
        label:
          type: string
        url:
          type: string
          nullable: true
          format: uri
          description: Provider URL when available. Null means the provider withheld a destination.
      required:
      - kind
      - label
      - url
    InboxAccountIdentity:
      type: object
      description: The connected profile that receives this conversation and sends its replies.
      properties:
        id:
          type: string
        handle:
          type: string
        displayName:
          type: string
          nullable: true
        avatarUrl:
          type: string
          nullable: true
      required:
      - id
      - handle
      - displayName
      - avatarUrl