openapi: 3.0.1
info:
  title: Upload-Post Analytics Users API
  description: The Upload-Post API is a universal social media publishing interface for publishing videos, photos, and text posts to TikTok, Instagram, YouTube, LinkedIn, Facebook, X (Twitter), Threads, Pinterest, Bluesky, Reddit, Discord, Telegram, and Google Business Profile. It also manages user profiles, single-use JWT account-linking URLs, upload status/history, and cross-platform analytics.
  termsOfService: https://www.upload-post.com/terms
  contact:
    name: Upload-Post Support
    url: https://www.upload-post.com/
  version: '1.0'
servers:
- url: https://api.upload-post.com/api
  description: Upload-Post production API
security:
- ApikeyAuth: []
tags:
- name: Users
  description: Manage user profiles and social account linking.
paths:
  /uploadposts/users:
    get:
      operationId: listUsers
      tags:
      - Users
      summary: List user profiles
      description: Retrieves all user profiles created under the API key.
      responses:
        '200':
          description: Profiles retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      tags:
      - Users
      summary: Create a user profile
      description: Creates a new user profile identified by a unique username.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '200':
          description: Profile created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteUser
      tags:
      - Users
      summary: Delete a user profile
      description: Removes a user profile and its associated social connections.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteUserRequest'
      responses:
        '200':
          description: Profile deleted.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /uploadposts/users/{username}:
    get:
      operationId: getUser
      tags:
      - Users
      summary: Get a user profile
      description: Fetches details for a single profile by username.
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Profile retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /uploadposts/users/generate-jwt:
    post:
      operationId: generateJwt
      tags:
      - Users
      summary: Generate a JWT account-linking URL
      description: Creates a secure single-use URL that an end user visits to link their social media accounts to the given profile.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateJwtRequest'
      responses:
        '200':
          description: Linking URL generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateJwtResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /uploadposts/users/validate-jwt:
    post:
      operationId: validateJwt
      tags:
      - Users
      summary: Validate a JWT token
      description: Verifies a JWT token passed in the Authorization header and returns the associated profile details.
      responses:
        '200':
          description: Token validated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /uploadposts/me:
    get:
      operationId: getMe
      tags:
      - Users
      summary: Validate API key and get account info
      description: Validates the API key and returns information about the account.
      responses:
        '200':
          description: Account info retrieved.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    UserProfileList:
      type: object
      properties:
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
    UserProfile:
      type: object
      properties:
        username:
          type: string
        social_accounts:
          type: object
          description: Connected social accounts for the profile.
        created_at:
          type: string
          format: date-time
    Platform:
      type: string
      description: Target social platform.
      enum:
      - tiktok
      - instagram
      - youtube
      - linkedin
      - facebook
      - x
      - threads
      - pinterest
      - bluesky
      - reddit
      - discord
      - telegram
      - google-business
    GenerateJwtResponse:
      type: object
      properties:
        access_url:
          type: string
          description: Single-use URL the end user visits to link accounts.
    GenerateJwtRequest:
      type: object
      required:
      - username
      properties:
        username:
          type: string
          description: Profile the linking URL is generated for.
        redirect_url:
          type: string
          description: URL to redirect the user to after linking.
        logo_image:
          type: string
          description: Logo image to display on the linking page.
        platforms:
          type: array
          items:
            $ref: '#/components/schemas/Platform'
          description: Restrict the linking flow to specific platforms.
        language:
          type: string
          description: Language of the linking page.
    DeleteUserRequest:
      type: object
      required:
      - username
      properties:
        username:
          type: string
          description: Username of the profile to remove.
    CreateUserRequest:
      type: object
      required:
      - username
      properties:
        username:
          type: string
          description: Unique identifier for the user profile.
    Error:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Provide the header in the form `Authorization: Apikey YOUR_API_KEY`.'