postzen-dev Media API

openapi: 3.2.0
info:
  title: PostZen Public Media API
  version: 1.0.0
  description: The PostZen Public API lets server-side integrations manage profiles, connected social accounts, OAuth connection flows, media uploads, post creation, and outbound webhooks.
servers:
- url: https://api.postzen.dev
  description: Production API
security:
- bearerAuth: []
tags:
- name: Media
  description: Create presigned upload URLs for PostZen-hosted media, or upload a small file directly.
paths:
  /v1/media/presign:
    post:
      tags:
      - Media
      operationId: createMediaPresign
      summary: Create a presigned media upload URL
      description: Creates a presigned URL for uploading an image, video, GIF, or PDF to PostZen-hosted storage. Upload the file with an HTTP `PUT` to `uploadUrl`, then reference `publicUrl` in post `mediaItems`. This endpoint requires a read-write API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaPresignRequest'
            example:
              filename: launch-video.mp4
              contentType: video/mp4
              size: 10485760
      responses:
        '200':
          description: Presigned upload URL created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaPresignResponse'
              example:
                uploadUrl: https://postzen-media.a1b2c3d4e5f6a7b8.r2.cloudflarestorage.com/users/jd7cm2xw9krt4v1n8q6zs0b3hf5yg2pa/media/6f0d0296-6a1c-4d5b-9a2e-3f8c1b7d4e90/launch-video.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=f3ac1e2b
                publicUrl: https://media.postzen.dev/users/jd7cm2xw9krt4v1n8q6zs0b3hf5yg2pa/media/6f0d0296-6a1c-4d5b-9a2e-3f8c1b7d4e90/launch-video.mp4
                key: users/jd7cm2xw9krt4v1n8q6zs0b3hf5yg2pa/media/6f0d0296-6a1c-4d5b-9a2e-3f8c1b7d4e90/launch-video.mp4
                type: video
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/media/upload-direct:
    post:
      tags:
      - Media
      operationId: uploadMediaDirect
      summary: Upload a file directly
      description: Uploads a file in the request itself and returns a public URL, for cases where a two-step presign is inconvenient and the file is small — chiefly direct message attachments, where Meta fetches the URL itself. The stored object is deleted automatically after seven days, so it is not a substitute for `POST /v1/media/presign` when publishing posts. Maximum 25MB. Requires a read-write API key.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The file bytes. Image, video, audio, or PDF, up to 25MB.
                contentType:
                  type: string
                  description: MIME type override, for clients that cannot set the part's own Content-Type.
      responses:
        '200':
          description: File stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaDirectUploadResponse'
              example:
                url: https://media.postzen.dev/direct-uploads/0001787068800000-6f0d0296-6a1c-4d5b-9a2e-3f8c1b7d4e90/receipt.jpg
                filename: receipt.jpg
                contentType: image/jpeg
                size: 184320
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    MediaPresignRequest:
      type: object
      required:
      - filename
      - contentType
      properties:
        filename:
          type: string
          description: Original file name. PostZen sanitizes it for storage.
        contentType:
          type: string
          enum:
          - image/jpeg
          - image/jpg
          - image/png
          - image/webp
          - image/gif
          - video/mp4
          - video/mpeg
          - video/quicktime
          - video/avi
          - video/x-msvideo
          - video/webm
          - video/x-m4v
          - application/pdf
        size:
          type: integer
          minimum: 0
          maximum: 5368709120
          description: File size in bytes.
        profileId:
          type: string
          description: Optional profile scope. If provided, the API key must have access to the profile.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        type:
          type: string
        code:
          type: string
        param:
          type:
          - string
          - 'null'
    MediaPresignResponse:
      type: object
      required:
      - uploadUrl
      - publicUrl
      - key
      - type
      properties:
        uploadUrl:
          type: string
          format: uri
          description: Use this URL for the direct file upload.
        publicUrl:
          type: string
          format: uri
          description: Use this URL in post `mediaItems`.
        key:
          type: string
        type:
          type: string
          enum:
          - image
          - video
          - gif
          - document
    RateLimitError:
      type: object
      required:
      - error
      - retryAfter
      properties:
        error:
          type: string
          const: rate_limited
        retryAfter:
          type: integer
          minimum: 1
          description: Number of seconds to wait before retrying.
    MediaDirectUploadResponse:
      type: object
      required:
      - url
      - filename
      - contentType
      - size
      properties:
        url:
          type: string
          format: uri
          description: Publicly fetchable URL for the stored file. Pass it as `attachmentUrl` when sending a direct message.
        filename:
          type: string
          description: Sanitized file name the object was stored under.
        contentType:
          type: string
        size:
          type: integer
          description: Stored size in bytes.
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Not found
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: JSON body is required
    TooManyRequests:
      description: Rate limit exceeded. Retry after the interval indicated by the `Retry-After` header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: rate_limited
            retryAfter: 30
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorized
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Failed to create post
    Forbidden:
      description: The API key does not have sufficient permission or profile access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: API key requires read_write permission
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: PostZen API key.