PostOnce Accounts API

openapi: 3.2.0
info:
  title: PostOnce Public Accounts API
  version: 1.0.0-alpha
  description: Public API for PostOnce paid users
servers:
- url: https://postonce.to/api/public
security:
- bearerAuth: []
tags:
- name: Accounts
paths:
  /v1/accounts:
    get:
      summary: List accounts
      description: Returns all social accounts owned by the API key profile, including disconnected accounts.
      responses:
        '200':
          description: Accounts returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
        '401':
          description: Missing, invalid, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
      tags:
      - Accounts
      operationId: getV1Accounts
      x-operation-id-source: derived
  /v1/accounts/{id}:
    delete:
      summary: Disconnect account
      description: Removes PostOnce access to an owned social account. The account is disconnected with its credentials cleared (the response returns deleted=false and disconnected=true); its posts and history are kept, and reconnecting the same account restores posting. Farcaster, Nostr, and Telegram records are also disabled. Farcaster signer revocation requires a separate provider step; Nostr remote-signer logout is best effort; @PostOnceBot leaves a Telegram channel on a best-effort basis when no other PostOnce account uses it. This does not delete published social content.
      parameters:
      - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Account disconnected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          description: Missing, invalid, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '404':
          description: Account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Accounts
      operationId: deleteV1AccountsById
      x-operation-id-source: derived
  /v1/accounts/connect/{platform}:
    post:
      summary: Connect account
      description: Computes a five-minute browser authorization URL bound to the authenticated profile without connecting or changing an account. Open the returned URL in a separate browser step to authorize the provider; then list accounts to verify connection. Depending on platform, the browser uses provider OAuth or a PostOnce-hosted credential or signer flow. Never enter provider credentials in chat.
      parameters:
      - $ref: '#/components/parameters/platform'
      responses:
        '201':
          description: Account connection URL created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectAccountResponse'
        '401':
          description: Missing, invalid, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '403':
          description: Missing required scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported platform.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Accounts
      operationId: postV1AccountsConnectByPlatform
      x-operation-id-source: derived
components:
  schemas:
    AuthErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            hint:
              type: string
              description: Suggested action to resolve the error.
            code:
              type: string
              example: invalid_api_key
            message:
              type: string
              example: Invalid API key.
    ConnectAccountResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            hosted_url:
              type: string
              nullable: true
              example: https://postonce.to/dashboard/accounts?connect=twitter&source=public_api
            authorization_url:
              type: string
              nullable: true
              description: Five-minute browser connection URL bound to the API-key profile with signed state. OAuth platforms return a direct provider URL; Bluesky returns a PostOnce-hosted app-password form; Farcaster returns a PostOnce-hosted managed-signer approval flow; Nostr returns a PostOnce-hosted NIP-46 remote-signer flow; Telegram returns a PostOnce-hosted flow that adds @PostOnceBot as a channel admin.
              example: https://www.tiktok.com/v2/auth/authorize/?client_key=...
            mode:
              type: string
              enum:
              - credential_form_url
              - managed_signer
              - remote_signer
              - oauth_authorization_url
              example: oauth_authorization_url
            platform:
              type: string
              example: twitter
    DeleteResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            deleted:
              type: boolean
              example: true
            id:
              type: string
            provider_revocation_required:
              type: boolean
              nullable: true
              description: True when local PostOnce access is removed but the provider requires the user to revoke the remote signer separately.
            provider_revocation_url:
              type: string
              nullable: true
            message:
              type: string
              nullable: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            hint:
              type: string
              description: Suggested action to resolve the error.
            code:
              type: string
              example: workflow_limit_reached
            message:
              type: string
              example: You have reached the maximum number of workflows for your plan.
    Account:
      type: object
      properties:
        id:
          type: string
        platform:
          type: string
          enum:
          - bluesky
          - facebook
          - farcaster
          - nostr
          - telegram
          - instagram
          - linkedin
          - pinterest
          - reddit
          - snapchat
          - threads
          - tiktok
          - twitter
          - vimeo
          - youtube
          example: twitter
        username:
          type: string
          example: nigelyong
        avatar_url:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - active
          - auth_required
          - disconnected
          example: active
        capabilities:
          type: object
          nullable: true
          description: Discoverable account capabilities used by both the public API and generated MCP tools.
          properties:
            connection_mode:
              type: string
            destination:
              type: boolean
            source:
              type: boolean
            backfill:
              type: boolean
            text:
              type: boolean
            images:
              type: boolean
            video:
              type: boolean
            replies:
              type: boolean
            threads:
              type: boolean
        media_requirements:
          type: object
          nullable: true
          description: Media input constraints from PostOnce's publishing validator. Check required_media before a text-only post. Platform-level guidance is not proof of current account authorization or delivery success. Format conversions remain subject to processing limits.
          properties:
            supported_formats:
              type: array
              items:
                type: string
            convertible_formats:
              type: object
              additionalProperties:
                type: string
            max_size_bytes:
              type: object
              properties:
                image:
                  type: integer
                video:
                  type: integer
                gif:
                  type: integer
            file_constraints:
              type: object
              description: maxFiles, maxVideoFiles, maxImageFiles, optional maxGifFiles, allowMixedMedia and optional gifBehavior.
              additionalProperties: true
            required_media:
              type: object
              nullable: true
              description: 'When present: minFiles and acceptedTypes (image/video) define mandatory media, with errorCode and errorMessage.'
              additionalProperties: true
            max_hashtags:
              type: integer
              minimum: 0
              nullable: true
            min_video_duration_seconds:
              type: number
              nullable: true
            max_video_duration_seconds:
              type: number
              nullable: true
            aspect_ratio:
              type: object
              nullable: true
              additionalProperties: true
            thumbnail:
              type: object
              nullable: true
              additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  parameters:
    platform:
      name: platform
      in: path
      required: true
      schema:
        type: string
        enum:
        - bluesky
        - facebook
        - farcaster
        - nostr
        - telegram
        - instagram
        - linkedin
        - pinterest
        - reddit
        - snapchat
        - threads
        - tiktok
        - twitter
        - vimeo
        - youtube
      description: Social platform to connect.
    accountId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Connected account ID.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Scoped API key issued in PostOnce Settings. OAuth authorization grants are not currently supported.
      x-scopes:
        accounts:read: List and read connected accounts.
        accounts:write: Connect and disconnect social accounts.
        media:read: Read uploaded media.
        media:write: Upload media.
        posts:read: Read posts and unpublished drafts.
        posts:write: Create, update, publish, cancel, retry, and delete posts and drafts.
        workflows:read: List and read crossposting workflows.
        workflows:write: Create, update, and delete crossposting workflows.