postproxy-dev API Keys API

openapi: 3.2.0
info:
  title: Postproxy Social Media API Keys API
  version: '2026-09-21'
  summary: Unified social media API for publishing, comments, direct messages, and reviews.
  description: 'The Postproxy API lets you programmatically create and manage social media posts across Facebook, Instagram, TikTok, LinkedIn, YouTube, X (Twitter), Threads, Pinterest, Bluesky, Telegram, and Google Business. Beyond publishing you can read and reply to comments, read and send direct messages, and reply to Google Business reviews and Facebook Page recommendations.


    Send one payload; Postproxy maps it to each platform''s rules and returns a per-platform outcome. Sandbox mode is included on all plans for development without real accounts.


    Human-readable reference: https://postproxy.dev/reference/overview/


    ## Versioning and deprecation


    The API has a single stable version served at https://api.postproxy.dev/api. Releases are identified by this document''s date-based `info.version`. Changes are additive: new endpoints, new optional parameters, and new response fields may appear, and clients should ignore fields they do not recognize. Existing fields, parameters, and status codes are not changed or removed without a deprecation cycle.


    When an endpoint or field is deprecated it is marked `deprecated: true` in this specification and announced in the changelog (https://postproxy.dev/getting-started/changelog/) at least 90 days before removal.'
  termsOfService: https://postproxy.dev/terms-conditions/
  contact:
    name: Postproxy Support
    url: https://postproxy.dev/developers/
    email: support@postproxy.dev
  x-versioning:
    strategy: stable-single-version
    spec-version-format: date (YYYY-MM-DD)
    compatibility: additive-only; breaking changes go through a deprecation cycle
    deprecation-signal: 'deprecated: true in this spec, plus a changelog announcement at least 90 days before removal'
    changelog: https://postproxy.dev/getting-started/changelog/
servers:
- url: https://api.postproxy.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: API Keys
  description: Provision and revoke profile-group-scoped API keys. All endpoints require an account-wide API key.
paths:
  /api/api_keys:
    get:
      operationId: api_keys_list
      summary: List API keys
      description: Returns the profile-group-scoped API keys in the caller's environment, newest first. Tokens are never included. Requires an account-wide API key; group-scoped keys and OAuth tokens get 422.
      tags:
      - API Keys
      externalDocs:
        url: https://postproxy.dev/reference/api-keys/#list-api-keys
      responses:
        '200':
          description: Scoped API keys, without tokens
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
        '422':
          description: Caller is a group-scoped key or an OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: api_keys_create
      summary: Create API key
      description: 'Creates an API key scoped to a profile group. The response is the only place the token is returned - store it immediately. Requires an account-wide API key; only scoped keys can be minted, so there is no API path to a second account-wide key. Keys are environment-bound: the target profile group must be in the caller''s environment. Send an Idempotency-Key header to make the call safe to retry - a retried create returns the original key rather than minting a second one.'
      tags:
      - API Keys
      externalDocs:
        url: https://postproxy.dev/reference/api-keys/#create-api-key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - profile_group_id
              properties:
                profile_group_id:
                  type: string
                  description: Profile group to scope the key to. Must belong to your account and match the caller's environment.
                name:
                  type: string
                  description: Label for the key, shown in the web app.
      responses:
        '201':
          description: The created key, token included (returned only here)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          description: profile_group_id does not resolve to a group of your account in this environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: profile_group_id missing, or the caller is a group-scoped key or an OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrors'
  /api/api_keys/{id}:
    delete:
      operationId: api_keys_revoke
      summary: Revoke API key
      description: 'Revokes a scoped API key immediately: the next request with that token returns 401. Only scoped keys in the caller''s environment can be revoked; any other id returns 404. Requires an account-wide API key.'
      tags:
      - API Keys
      externalDocs:
        url: https://postproxy.dev/reference/api-keys/#revoke-api-key
      parameters:
      - name: id
        in: path
        required: true
        description: API key ID
        schema:
          type: string
      responses:
        '200':
          description: Key revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
        '404':
          description: Not a scoped key in the caller's environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Caller is a group-scoped key or an OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ApiKey:
      type: object
      properties:
        id:
          type: string
          description: API key ID, used in the revoke URL.
        name:
          type:
          - string
          - 'null'
          description: Label given to the key.
        profile_group_id:
          type: string
          description: The profile group the key is scoped to.
        sandbox:
          type: boolean
          description: true for sandbox keys.
        token:
          type: string
          description: The secret bearer token. Returned only in the create response.
        created_at:
          type: string
          format: date-time
    ValidationErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
      required:
      - errors
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key sent as a Bearer token in the Authorization header. Keys are either full-access (entire account) or scoped to a single profile group. Create keys at https://app.postproxy.dev under Settings → API Keys.
externalDocs:
  description: Full API reference
  url: https://postproxy.dev/reference/overview/