openapi: 3.1.0
info:
  title: Agent Media Tools API
  version: 2.0.0
  description: 'Free online media processing & agent utilities: images, PDFs, QR,
    pastebin, webhooks, crypto tools, and more. Every tool is a REST endpoint.


    Base URL: https://agentmediatools.com

    Anonymous: 10 tool uses/day

    Logged-in free: 25/day

    Agent API (Bearer): 25/day free, 1,000/day Premium'
  contact:
    url: https://agentmediatools.com
servers:
- url: https://agentmediatools.com
  description: Production
- url: http://localhost:3000
  description: Development
paths:
  /api/health:
    get:
      tags:
      - System
      summary: Health check
      operationId: healthCheck
      responses:
        '200':
          description: OK
  /api/ip:
    get:
      tags:
      - Dev Tools
      summary: Get your IP address and geolocation
      operationId: ipLookup
      responses:
        '200':
          description: IP info
  /api/uuid:
    get:
      tags:
      - Dev Tools
      summary: Generate a random UUID v4
      operationId: generateUuid
      responses:
        '200':
          description: UUID
  /api/password:
    get:
      tags:
      - Dev Tools
      summary: Generate a secure random password
      operationId: generatePassword
      parameters:
      - name: length
        in: query
        schema:
          type: integer
        description: Password length (default 16)
      - name: numbers
        in: query
        schema:
          type: boolean
        description: Include numbers
      - name: symbols
        in: query
        schema:
          type: boolean
        description: Include symbols
      responses:
        '200':
          description: Password
  /api/timestamp:
    get:
      tags:
      - Dev Tools
      summary: Convert between unix timestamps and dates
      operationId: timestampConvert
      parameters:
      - name: value
        in: query
        schema:
          type: string
        description: Timestamp or date string
      responses:
        '200':
          description: Conversion result
  /api/base64:
    get:
      tags:
      - Dev Tools
      summary: Base64 encode or decode
      operationId: base64Convert
      parameters:
      - name: text
        in: query
        required: true
        schema:
          type: string
      - name: action
        in: query
        required: true
        schema:
          type: string
          enum:
          - encode
          - decode
      responses:
        '200':
          description: Result
  /api/hash:
    get:
      tags:
      - Dev Tools
      summary: Generate cryptographic hash (MD5, SHA-1/256/384/512)
      operationId: generateHash
      parameters:
      - name: text
        in: query
        required: true
        schema:
          type: string
      - name: algo
        in: query
        schema:
          type: string
          enum:
          - md5
          - sha1
          - sha256
          - sha384
          - sha512
      responses:
        '200':
          description: Hash result
  /api/units:
    get:
      tags:
      - Dev Tools
      summary: Convert between units (length, weight, temp, data, time)
      operationId: unitConvert
      parameters:
      - name: value
        in: query
        required: true
        schema:
          type: number
      - name: from
        in: query
        required: true
        schema:
          type: string
      - name: to
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Conversion result
  /api/diff:
    get:
      tags:
      - Dev Tools
      summary: Compare two texts and return the diff
      operationId: textDiff
      parameters:
      - name: a
        in: query
        required: true
        schema:
          type: string
      - name: b
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Diff result
  /api/search:
    get:
      tags:
      - Discovery
      summary: Search available tools
      operationId: searchTools
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Search results
  /api/tools:
    get:
      tags:
      - Discovery
      summary: List all available tools
      operationId: listTools
      responses:
        '200':
          description: Tool list
  /api/tools/stats:
    get:
      tags:
      - Discovery
      summary: Get tool usage statistics
      operationId: toolStats
      responses:
        '200':
          description: Stats
  /api/stats/live:
    get:
      tags:
      - Stats
      summary: 'Live platform usage stats: requests today, bot breakdown, top tools'
      operationId: liveStats
      responses:
        '200':
          description: Live stats
  /api/stats/bots:
    get:
      tags:
      - Stats
      summary: AI crawler/bot analytics
      operationId: botStats
      responses:
        '200':
          description: Bot analytics
  /api/agent-docs:
    get:
      tags:
      - Agent
      summary: Get agent integration documentation
      operationId: agentDocs
      responses:
        '200':
          description: Agent docs
  /api/agent/status:
    get:
      tags:
      - Agent
      summary: Check agent API key status and usage
      operationId: agentStatus
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Status
  /api/shop/items:
    get:
      tags:
      - Shop
      summary: List purchasable scripts and bundles
      operationId: shopItems
      responses:
        '200':
          description: Shop items
  /api/paste:
    post:
      tags:
      - Pastebin
      summary: Create a text paste
      operationId: createPaste
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: Text content (max 500KB)
                title:
                  type: string
                syntax:
                  type: string
                  enum:
                  - text
                  - json
                  - javascript
                  - python
                  - html
                  - css
                  - bash
                  - yaml
                expires_in_hours:
                  type: number
              required:
              - content
      responses:
        '200':
          description: Created paste with slug
  /api/shorten:
    post:
      tags:
      - URL Shortener
      summary: Create a short redirect URL
      operationId: shortenUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
              required:
              - url
      responses:
        '200':
          description: Short URL
  /api/burn-note:
    post:
      tags:
      - Burn Notes
      summary: Create a self-destructing note
      operationId: createBurnNote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                max_views:
                  type: integer
              required:
              - content
      responses:
        '200':
          description: Burn note URL
  /api/dead-drop:
    post:
      tags:
      - Dead Drops
      summary: Create a one-time passphrase-protected message
      operationId: createDeadDrop
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                passphrase:
                  type: string
              required:
              - content
      responses:
        '200':
          description: Dead drop slug and claim URL
  /api/dead-drop/{slug}:
    get:
      tags:
      - Dead Drops
      summary: Claim (read) a one-time dead drop message
      operationId: claimDeadDrop
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: passphrase
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Message content
        '404':
          description: Not found or consumed
  /api/qrcode:
    post:
      tags:
      - QR Code
      summary: Generate a QR code from text or URL
      operationId: generateQr
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
              required:
              - text
      responses:
        '200':
          description: QR code image
  /api/jwt-decode:
    post:
      tags:
      - JWT
      summary: Decode a JWT token (header + payload)
      operationId: jwtDecode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
              required:
              - token
      responses:
        '200':
          description: Decoded header and payload
  /api/json-format:
    post:
      tags:
      - JSON
      summary: Format, validate, or prettify JSON
      operationId: jsonFormat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: string
                action:
                  type: string
                  enum:
                  - format
                  - validate
              required:
              - input
      responses:
        '200':
          description: Formatted or validated result
  /api/csv-convert:
    post:
      tags:
      - CSV
      summary: Convert between JSON and CSV
      operationId: csvConvert
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: string
                direction:
                  type: string
                  enum:
                  - json2csv
                  - csv2json
              required:
              - input
              - direction
      responses:
        '200':
          description: Converted data
  /api/token-count:
    post:
      tags:
      - Tokens
      summary: Count tokens in text (LLM-style estimation)
      operationId: countTokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
              required:
              - text
      responses:
        '200':
          description: Token count
  /api/resize-image:
    post:
      tags:
      - Image Tools
      summary: Resize/convert an image (JPEG, PNG, WebP, AVIF)
      operationId: resizeImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                width:
                  type: integer
                height:
                  type: integer
                format:
                  type: string
                  enum:
                  - jpeg
                  - png
                  - webp
                  - avif
              required:
              - image
      responses:
        '200':
          description: Resized image
  /api/convert-image:
    post:
      tags:
      - Image Tools
      summary: Convert image format with quality control
      operationId: convertImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                format:
                  type: string
                  enum:
                  - jpeg
                  - png
                  - webp
                  - avif
                quality:
                  type: integer
                  minimum: 1
                  maximum: 100
              required:
              - image
      responses:
        '200':
          description: Converted image
  /api/compress-image:
    post:
      tags:
      - Image Tools
      summary: Compress image with quality setting
      operationId: compressImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                quality:
                  type: integer
                  minimum: 1
                  maximum: 100
              required:
              - image
      responses:
        '200':
          description: Compressed image
  /api/analyze-image:
    post:
      tags:
      - Image Tools
      summary: Extract image metadata (dimensions, format, EXIF)
      operationId: analyzeImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
              required:
              - image
      responses:
        '200':
          description: Image metadata
  /api/crop-image:
    post:
      tags:
      - Image Tools
      summary: Crop image to specific dimensions
      operationId: cropImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                width:
                  type: integer
                height:
                  type: integer
                x:
                  type: integer
                y:
                  type: integer
              required:
              - image
              - width
              - height
      responses:
        '200':
          description: Cropped image
  /api/merge-pdf:
    post:
      tags:
      - PDF Tools
      summary: Merge multiple PDFs into one
      operationId: mergePdf
      security:
      - CookieAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pdfs:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: PDF files (max 10)
              required:
              - pdfs
      responses:
        '200':
          description: Merged PDF
  /api/split-pdf:
    post:
      tags:
      - PDF Tools
      summary: Split PDF into individual pages
      operationId: splitPdf
      security:
      - CookieAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pdf:
                  type: string
                  format: binary
              required:
              - pdf
      responses:
        '200':
          description: ZIP of individual pages
  /api/compress-pdf:
    post:
      tags:
      - PDF Tools
      summary: Compress PDF file size
      operationId: compressPdf
      security:
      - CookieAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pdf:
                  type: string
                  format: binary
              required:
              - pdf
      responses:
        '200':
          description: Compressed PDF
  /api/pdf-rotate:
    post:
      tags:
      - PDF Tools
      summary: Rotate PDF pages
      operationId: rotatePdf
      security:
      - CookieAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pdf:
                  type: string
                  format: binary
                angle:
                  type: integer
                  enum:
                  - 90
                  - 180
                  - 270
                pages:
                  type: string
              required:
              - pdf
      responses:
        '200':
          description: Rotated PDF
  /api/pdf-to-text:
    post:
      tags:
      - PDF Tools
      summary: Extract text from PDF
      operationId: pdfToText
      security:
      - CookieAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pdf:
                  type: string
                  format: binary
              required:
              - pdf
      responses:
        '200':
          description: Extracted text
  /api/pdf-to-images:
    post:
      tags:
      - PDF Tools
      summary: Convert PDF pages to PNG images
      operationId: pdfToImages
      security:
      - CookieAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pdf:
                  type: string
                  format: binary
              required:
              - pdf
      responses:
        '200':
          description: ZIP of page images
  /api/images-to-pdf:
    post:
      tags:
      - PDF Tools
      summary: Combine images into a PDF
      operationId: imagesToPdf
      security:
      - CookieAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                images:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Images (max 50)
              required:
              - images
      responses:
        '200':
          description: Generated PDF
  /api/webhook-inbox:
    post:
      tags:
      - Webhooks
      summary: Create a webhook inbox (receive HTTP requests for inspection)
      operationId: createWebhook
      security:
      - CookieAuth: []
      responses:
        '200':
          description: Webhook inbox URL
  /api/chain:
    post:
      tags:
      - Tool Chaining
      summary: Chain multiple tool outputs as subsequent tool inputs
      operationId: chainTools
      responses:
        '200':
          description: Chain result
  /api/pipeline/run:
    post:
      tags:
      - Pipeline
      summary: Run a multi-step processing pipeline
      operationId: runPipeline
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Pipeline run result
  /api/agent/pdf-to-text:
    post:
      tags:
      - Agent API
      summary: PDF text extraction (agent-authenticated)
      operationId: agentPdfToText
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pdf:
                  type: string
                  format: binary
              required:
              - pdf
      responses:
        '200':
          description: Extracted text
  /api/agent/images-to-pdf:
    post:
      tags:
      - Agent API
      summary: Combine images into PDF (agent-authenticated)
      operationId: agentImagesToPdf
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                images:
                  type: array
                  items:
                    type: string
                    format: binary
                required:
                - images
      responses:
        '200':
          description: Generated PDF
  /api/agent/pdf-to-images:
    post:
      tags:
      - Agent API
      summary: Convert PDF pages to images (agent-authenticated)
      operationId: agentPdfToImages
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pdf:
                  type: string
                  format: binary
              required:
              - pdf
      responses:
        '200':
          description: ZIP of images
  /api/agent/crop-image:
    post:
      tags:
      - Agent API
      summary: Crop image by URL (agent-authenticated)
      operationId: agentCropImage
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                width:
                  type: integer
                height:
                  type: integer
                x:
                  type: integer
                y:
                  type: integer
              required:
              - image_url
              - width
              - height
      responses:
        '200':
          description: Cropped image
  /api/agent/video-download:
    post:
      tags:
      - Agent API
      summary: Download video from URL (agent-authenticated)
      operationId: agentVideoDownload
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Video file
  /api/agent/audio-extract:
    post:
      tags:
      - Agent API
      summary: Extract audio from video URL (agent-authenticated)
      operationId: agentAudioExtract
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Audio file
  /api/agent/image-proxy:
    post:
      tags:
      - Agent API
      summary: Proxy and optionally transform images (agent-authenticated)
      operationId: agentImageProxy
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Image content
  /api/agent/scrape:
    post:
      tags:
      - Agent API
      summary: Scrape web page content (agent-authenticated)
      operationId: agentScrape
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Scraped content
  /api/agent/video-info:
    post:
      tags:
      - Agent API
      summary: Get video metadata (agent-authenticated)
      operationId: agentVideoInfo
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Video metadata
  /api/agent/shop/checkout:
    post:
      tags:
      - Shop
      summary: Purchase scripts/bundles as an agent
      operationId: agentShopCheckout
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Checkout URL
  /api/agent/keys:
    post:
      tags:
      - Agent Auth
      summary: Create a new agent API key
      operationId: createAgentKey
      security:
      - CookieAuth: []
      responses:
        '200':
          description: API key
  /api/agent/provision:
    post:
      tags:
      - Agent Auth
      summary: Invite a human to activate an account (magic-link email verification)
      description: |
        Creates a pending invite and emails a magic link. Returns claim_url for the agent to share directly.
        Email is verified when the human opens the link and sets a password — no separate OTP.
        Limits: 1 invite per IP per 24h; 5 per agent key per 24h; 1 pending invite per email.
      operationId: agentProvision
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                  description: Human display name for the invite email
                agent_label:
                  type: string
                  description: Agent name shown in the invite (defaults to key name)
      responses:
        '201':
          description: Invite created with claim_url
        '409':
          description: Email already registered or pending invite exists
        '429':
          description: IP or agent-key provision limit reached
  /api/agent/provision/lookup:
    get:
      tags:
      - Agent Auth
      summary: Validate activation token (for /activate page)
      operationId: agentProvisionLookup
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Valid pending invite (email masked)
        '404':
          description: Invalid token
        '410':
          description: Expired or already claimed
  /api/agent/provision/claim:
    post:
      tags:
      - Agent Auth
      summary: Human activates account via magic-link token
      operationId: agentProvisionClaim
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              - password
              properties:
                token:
                  type: string
                password:
                  type: string
                  minLength: 6
      responses:
        '200':
          description: Account created with one-time api_key
        '410':
          description: Expired or already claimed invite
  '/api/agent/provision/{id}':
    get:
      tags:
      - Agent Auth
      summary: Poll provision status; retrieve one-time api_key after claim
      operationId: agentProvisionStatus
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Provision status (api_key shown once when claimed)
        '403':
          description: Provision created by a different agent key
        '404':
          description: Not found
  /activate:
    get:
      tags:
      - Agent Auth
      summary: Human account activation page
      operationId: activatePage
      responses:
        '200':
          description: HTML activation form
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Agent API keys. Get one at https://agentmediatools.com (login →
        Agent Keys)
    CookieAuth:
      type: apiKey
      in: cookie
      name: connect.sid
      description: Session cookie for web UI login users
tags:
- name: Image Tools
  description: Resize, convert, compress, crop, analyze images
- name: PDF Tools
  description: Merge, split, compress, rotate, extract PDFs
- name: Pastebin
  description: Create and share text pastes
- name: URL Shortener
  description: Create short redirect URLs
- name: Burn Notes
  description: Self-destructing notes
- name: Dead Drops
  description: One-time passphrase-protected messages
- name: QR Code
  description: Generate QR codes
- name: Webhooks
  description: Webhook receivers for inspection
- name: JWT
  description: JWT token decoding and inspection
- name: JSON
  description: JSON formatting, validation, conversion
- name: CSV
  description: JSON-CSV conversion
- name: Tokens
  description: LLM token counting
- name: Dev Tools
  description: UUID, password, hash, base64, units, timestamp, diff, IP
- name: Agent API
  description: Premium agent-authenticated endpoints
- name: Pipeline
  description: Multi-step processing pipelines
- name: Tool Chaining
  description: Chain tool outputs to inputs
- name: Discovery
  description: Platform discovery and search
- name: Stats
  description: Analytics and statistics
- name: Shop
  description: Scripts and bundles store
- name: Agent Auth
  description: API key management
- name: System
  description: Health checks and system info
externalDocs:
  description: Full documentation and interactive UI
  url: https://agentmediatools.com/docs