openapi: 3.1.0
info:
  title: Memesio API Contracts agent-infra uploads API
  version: 0.1.0
  description: Contract baseline for AI jobs, trend alerts, collaboration, and billing surfaces.
servers:
- url: /
tags:
- name: uploads
paths:
  /api/v1/memes/caption-upload:
    post:
      summary: Upload an Image, Place Top or Bottom Caption Boxes, and Store the Hosted Meme
      tags:
      - uploads
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - captions
              properties:
                file:
                  type: string
                  format: binary
                captions:
                  type: string
                  description: JSON array of caption slot objects with text, x, y, boxWidthPct, boxHeightPct, fontSize, and alignment fields.
                title:
                  type: string
                  maxLength: 140
                visibility:
                  type: string
                  enum:
                  - private
                  - public
                watermark:
                  type: string
                  description: Optional JSON watermark object. Non-premium callers are forced to the default Memesio watermark; premium callers can customize enabled, text, position, and scale.
      responses:
        '201':
          description: Uploaded meme created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadCaptionMemeSuccessResponse'
        '400':
          description: Validation error
        '401':
          description: Invalid API key when one is provided
        '415':
          description: Unsupported upload content
        '429':
          description: Rate limit exceeded
components:
  schemas:
    FreeMemeWatermark:
      type: object
      description: Caption API requests accept watermark input, but non-premium callers are forced to the default Memesio watermark. Premium callers can customize enabled, text, position, and scale.
      properties:
        enabled:
          type: boolean
        text:
          type: string
          maxLength: 64
        position:
          type: string
          enum:
          - top_left
          - top_right
          - bottom_left
          - bottom_right
        scale:
          type: number
          minimum: 0.6
          maximum: 3
    CaptionInput:
      type: object
      required:
      - text
      properties:
        id:
          type: string
          maxLength: 64
        text:
          type: string
          maxLength: 300
        x:
          type: number
        y:
          type: number
        fontSize:
          type: number
        boxWidthPct:
          type: number
        boxHeightPct:
          type: number
        maxLines:
          type: integer
          minimum: 1
        textAlign:
          type: string
          enum:
          - left
          - center
          - right
        fontFamily:
          type: string
          enum:
          - impact
          - arial
    UploadCaptionMemeSuccessResponse:
      type: object
      required:
      - ok
      - data
      properties:
        ok:
          type: boolean
          const: true
        data:
          type: object
          required:
          - slug
          - shareSlug
          - templateSlug
          - title
          - visibility
          - sourceImageUrl
          - imageUrl
          - canonicalImageUrl
          - altText
          - tags
          - apiUrl
          - pageUrl
          - ownerToken
          - captions
          - watermark
          properties:
            slug:
              type: string
            shareSlug:
              type: string
            templateSlug:
              type: string
            title:
              type: string
            visibility:
              type: string
              enum:
              - private
              - public
            sourceImageUrl:
              type: string
            imageUrl:
              type: string
            canonicalImageUrl:
              type: string
            altText:
              type: string
            tags:
              type: array
              items:
                type: string
            apiUrl:
              type: string
            pageUrl:
              type: string
            ownerToken:
              type: string
            captions:
              type: array
              items:
                $ref: '#/components/schemas/CaptionInput'
            watermark:
              $ref: '#/components/schemas/FreeMemeWatermark'
  securitySchemes:
    DeveloperApiKeyAuth:
      type: apiKey
      in: header
      name: x-developer-api-key
      description: 'Optional higher-rate free-tier auth. You can also send the key as Authorization: Bearer <key>.'
    AgentApiKeyAuth:
      type: apiKey
      in: header
      name: x-agent-api-key
      description: 'Agent auth for free endpoints and agent-admin routes. You can also send the key as Authorization: Bearer <key>.'