postlake-dev Credentials API

openapi: 3.2.0
info:
  title: PostLake Credentials 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: Credentials
  description: BYO platform app credentials (BYOK)
paths:
  /v1/credentials:
    post:
      tags:
      - Credentials
      summary: Save credentials
      description: Save BYO platform app credentials for supported networks other than X. X always uses PostLake's shared app; customer-owned X app credentials are rejected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                platform:
                  $ref: '#/components/schemas/Platform'
                clientId:
                  type: string
                clientSecret:
                  type: string
              required:
              - platform
              - clientId
              - clientSecret
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  credential:
                    $ref: '#/components/schemas/Credential'
                required:
                - credential
        '400':
          description: Invalid platform or missing credentials
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: postV1Credentials
      x-operation-id-source: derived
    get:
      tags:
      - Credentials
      summary: List credentials
      description: List BYO credentials
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  credentials:
                    type: array
                    items:
                      $ref: '#/components/schemas/Credential'
                required:
                - credentials
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getV1Credentials
      x-operation-id-source: derived
  /v1/credentials/{platform}:
    delete:
      tags:
      - Credentials
      summary: Delete credentials
      description: Delete BYO credentials for a platform
      parameters:
      - name: platform
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Platform'
      responses:
        '204':
          description: Deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Credentials not found
      operationId: deleteV1CredentialsByPlatform
      x-operation-id-source: derived
components:
  schemas:
    Credential:
      type: object
      properties:
        platform:
          $ref: '#/components/schemas/Platform'
        clientId:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
      - platform
      - clientId
      - createdAt
    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