openapi: 3.0.3
info:
  title: Datpaq ProAPI
  description: >
    Comprehensive multi-service API platform providing aviation, geolocation, financial, utilities, image processing,
    and data enrichment capabilities. All endpoints require authentication via API key passed as an x-api-key header or
    api_key query parameter.
  version: 1.0.0
  contact:
    name: Datpaq Support
    url: https://datpaq.com
  license:
    name: Proprietary
servers:
  - url: https://datpaq.com/api/v1
    description: Production
  - url: https://staging.datpaq.com/api/v1
    description: Staging
security:
  - ApiKeyHeader: []
  - ApiKeyQuery: []
tags:
  - name: Blog
    description: Public DATPAQ blog posts and company updates
  - name: Convert Time
    description: Timezone-aware datetime conversion
  - name: Current Time
    description: Current time by IANA timezone identifier
  - name: Image Processing
    description: Image resize, compress, convert, crop, and pipeline operations
  - name: IP Geolocation
    description: Geographic location data for IPv4 and IPv6 addresses
  - name: IP Intelligence
    description: Threat intelligence and risk scoring for IP addresses
  - name: Profanity
    description: Content moderation and profanity detection
  - name: Sample Data
    description: Mock data generation for testing and development (Faker.js)
  - name: Unit Conversion
    description: Unit conversion across 100+ measurement types
  - name: User Avatar
    description: Dynamic user avatar generation in PNG, WebP, or SVG
  - name: Validate IP
    description: IP address validation and classification (IPv4, IPv6, CIDR)
  - name: Web Screenshot
    description: Web page screenshot capture via headless browser
  - name: WHOIS
    description: Domain WHOIS registration data lookup
  - name: Working Days
    description: Business day calculations with regional holiday support
paths:
  /blog/posts:
    get:
      tags:
        - Blog
      operationId: blogListPosts
      summary: List latest blog posts
      description: Returns published DATPAQ blog posts, news, and press releases in reverse publication order.
      security: []
      parameters:
        - name: page
          in: query
          required: false
          description: Page number to return.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          description: Number of posts per page. Maximum 50.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
        - name: category
          in: query
          required: false
          description: Optional category filter. Supported values are all, press-release, news, and blog.
          schema:
            type: string
            enum:
              - all
              - press-release
              - news
              - blog
            default: all
        - name: tag
          in: query
          required: false
          description: Optional tag filter.
          schema:
            type: string
      responses:
        "200":
          description: Published blog posts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlogPostListResponse"
              example:
                success: true
                data:
                  - title: Introducing the Datpaq MCP Server
                    slug: introducing-the-datpaq-mcp-server
                    excerpt: Connect Datpaq APIs to any MCP-aware agent.
                    category: News
                    author: Datpaq Team
                    publishedAt: "2026-05-22T14:00:00.000Z"
                    tags:
                      - mcp
                      - agents
                pagination:
                  page: 1
                  limit: 10
                  totalPosts: 42
                  totalPages: 5
        "400":
          $ref: "#/components/responses/BadRequest"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /blog/posts/{slug}:
    get:
      tags:
        - Blog
      operationId: blogGetPost
      summary: Get a blog post by slug
      description: Returns a published DATPAQ blog post with rendered HTML and plain text content.
      security: []
      parameters:
        - name: slug
          in: path
          required: true
          description: Blog post slug.
          schema:
            type: string
            example: datpaq-launches-new-api-tools
      responses:
        "200":
          description: Blog post detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlogPostDetailResponse"
              example:
                success: true
                data:
                  title: Introducing the Datpaq MCP Server
                  slug: introducing-the-datpaq-mcp-server
                  content: |-
                    # Introducing the Datpaq MCP Server

                    Full post body in Markdown...
                  category: News
                  author: Datpaq Team
                  publishedAt: "2026-05-22T14:00:00.000Z"
                  tags:
                    - mcp
                    - agents
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /convert-time:
    get:
      tags:
        - Convert Time
      operationId: convertTime
      summary: Convert a datetime between timezones
      description: >
        Converts a datetime value from a source timezone to a target timezone. Accepts ISO 8601 strings, Unix epoch
        timestamps, or omit sourceTime to convert the current time.
      parameters:
        - name: sourceTime
          in: query
          required: false
          description: Time to convert (ISO 8601 or Unix ms). Defaults to current time.
          schema:
            type: string
            example: "2025-12-31T12:00:00Z"
        - name: sourceZone
          in: query
          required: true
          description: Source IANA timezone identifier
          schema:
            type: string
            example: America/New_York
        - name: targetZone
          in: query
          required: true
          description: Target IANA timezone identifier
          schema:
            type: string
            example: Europe/London
      responses:
        "200":
          description: Converted datetime with timezone metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  original_datetime: "2026-04-06T15:30:00"
                  original_timezone: America/New_York
                  converted_datetime: "2026-04-06T20:30:00"
                  converted_timezone: Europe/London
                  utc_datetime: "2026-04-06T19:30:00Z"
                  timezone_info:
                    from:
                      name: America/New_York
                      abbreviation: EDT
                      offset: "-04:00"
                      dst: true
                    to:
                      name: Europe/London
                      abbreviation: BST
                      offset: "+01:00"
                      dst: true
                meta:
                  correlation_id: conv_abc123
                  processing_time: 12ms
                  timestamp: "2026-04-06T19:30:00.000Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /current-time:
    get:
      tags:
        - Current Time
      operationId: currentTime
      summary: Get current time for an IANA timezone
      description: Returns the current date/time with UTC offset and DST status for a given timezone.
      parameters:
        - name: target
          in: query
          required: true
          description: IANA timezone identifier (e.g. America/New_York, UTC, Asia/Tokyo)
          schema:
            type: string
            example: America/New_York
      responses:
        "200":
          description: Current time data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  timezone: America/New_York
                  current_time: "2026-04-06T15:30:45-04:00"
                  utc_time: "2026-04-06T19:30:45Z"
                  timezone_info:
                    name: America/New_York
                    abbreviation: EDT
                    offset: "-04:00"
                    dst: true
                    dst_start: "2026-03-09T07:00:00Z"
                    dst_end: "2026-11-01T06:00:00Z"
                meta:
                  correlation_id: time_xyz789
                  processing_time: 8ms
                  timestamp: "2026-04-06T19:30:45.000Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /image-processing/process:
    post:
      tags:
        - Image Processing
      operationId: imagePipeline
      summary: Run an image through a multi-step operation pipeline
      description: >
        Executes an ordered array of image operations in a single request. Recommended over individual endpoints when
        multiple operations are needed. Supports resize, compress, convert, crop, and metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - operations
              properties:
                image_url:
                  type: string
                  format: uri
                  example: https://example.com/photo.jpg
                operations:
                  type: array
                  items:
                    type: object
                    required:
                      - operation
                    properties:
                      operation:
                        type: string
                        enum:
                          - resize
                          - compress
                          - convert
                          - crop
                          - metadata
                      width:
                        type: integer
                        minimum: 1
                      height:
                        type: integer
                        minimum: 1
                      quality:
                        type: integer
                        minimum: 1
                        maximum: 100
                      format:
                        type: string
                        enum:
                          - jpeg
                          - png
                          - webp
                          - avif
            example:
              image_url: https://example.com/photo.jpg
              operations:
                - type: resize
                  width: 800
                - type: convert
                  format: webp
      responses:
        "200":
          description: Processed image binary or JSON metadata
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /image-processing/resize:
    post:
      tags:
        - Image Processing
      operationId: imageResize
      summary: Resize an image to specified dimensions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                width:
                  type: integer
                  example: 800
                height:
                  type: integer
                  example: 600
                fit:
                  type: string
                  enum:
                    - cover
                    - contain
                    - fill
                    - inside
                    - outside
                  default: cover
            example:
              image_url: https://example.com/photo.jpg
              width: 800
              height: 600
              fit: cover
      responses:
        "200":
          description: Resized image binary
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /image-processing/compress:
    post:
      tags:
        - Image Processing
      operationId: imageCompress
      summary: Compress an image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                quality:
                  type: integer
                  minimum: 1
                  maximum: 100
                  example: 75
            example:
              image_url: https://example.com/photo.jpg
              quality: 80
      responses:
        "200":
          description: Compressed image binary
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /image-processing/convert:
    post:
      tags:
        - Image Processing
      operationId: imageConvert
      summary: Convert image to a different format
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - format
              properties:
                image_url:
                  type: string
                  format: uri
                format:
                  type: string
                  enum:
                    - jpeg
                    - png
                    - webp
                    - avif
                  example: webp
            example:
              image_url: https://example.com/photo.jpg
              format: webp
      responses:
        "200":
          description: Converted image binary
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /image-processing/crop:
    post:
      tags:
        - Image Processing
      operationId: imageCrop
      summary: Crop an image to a region
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - x
                - "y"
                - width
                - height
              properties:
                image_url:
                  type: string
                  format: uri
                x:
                  type: integer
                  minimum: 0
                "y":
                  type: integer
                  minimum: 0
                width:
                  type: integer
                  minimum: 1
                height:
                  type: integer
                  minimum: 1
            example:
              image_url: https://example.com/photo.jpg
              left: 0
              top: 0
              width: 400
              height: 400
      responses:
        "200":
          description: Cropped image binary
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /image-processing/metadata:
    post:
      tags:
        - Image Processing
      operationId: imageMetadata
      summary: Extract metadata from an image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
            example:
              image_url: https://example.com/photo.jpg
      responses:
        "200":
          description: Image metadata (dimensions, format, EXIF, color profile)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                format: jpeg
                width: 1920
                height: 1080
                size: 245760
                colorSpace: srgb
                hasAlpha: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /ip-geolocation:
    get:
      tags:
        - IP Geolocation
      operationId: ipGeolocationGet
      summary: Get geographic location for an IP address
      description: |
        Returns country, region, city, coordinates, ISP, ASN, and timezone for any IPv4 or IPv6 address.
      parameters:
        - name: ip
          in: query
          required: true
          schema:
            type: string
            example: 8.8.8.8
      responses:
        "200":
          description: Geolocation data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                ip: 8.8.8.8
                found: true
                location:
                  country: United States
                  region: California
                  city: Mountain View
                  latitude: 37.4056
                  longitude: -122.0775
                network:
                  network: 8.8.8.0/24
                  asn: AS15169
                  org: Google LLC
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
    post:
      tags:
        - IP Geolocation
      operationId: ipGeolocationPost
      summary: Get geographic location for an IP address (POST)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ip
              properties:
                ip:
                  type: string
                  example: 8.8.8.8
            example:
              ip: 8.8.8.8
      responses:
        "200":
          description: Geolocation data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                ip: 8.8.8.8
                found: true
                location:
                  country: United States
                  region: California
                  city: Mountain View
                  latitude: 37.4056
                  longitude: -122.0775
                network:
                  network: 8.8.8.0/24
                  asn: AS15169
                  org: Google LLC
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /ip-geolocation/batch:
    post:
      tags:
        - IP Geolocation
      operationId: ipGeolocationBatch
      summary: Batch IP geolocation lookup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ips
              properties:
                ips:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  example:
                    - 8.8.8.8
                    - 1.1.1.1
            example:
              ip:
                - 8.8.8.8
                - 1.1.1.1
              include_logs: false
      responses:
        "200":
          description: Geolocation data for each IP
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                summary:
                  total_requested: 2
                  valid_ips: 2
                  invalid_ips: 0
                  found: 2
                  not_found: 0
                  errors: 0
                  processing_time_ms: 125
                results:
                  - ip: 8.8.8.8
                    found: true
                    location:
                      country: United States
                      region: California
                      city: Mountain View
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /ip-intelligence:
    get:
      tags:
        - IP Intelligence
      operationId: ipIntelligenceGet
      summary: Get threat intelligence for an IP address
      description: >
        Returns trust score, risk classification, VPN/proxy/Tor detection, datacenter detection, and threat categories.
        Omit the ip parameter to analyze the caller's IP.
      parameters:
        - name: ip
          in: query
          required: false
          description: IP to analyze. Omits to use the caller's IP.
          schema:
            type: string
            example: 8.8.8.8
      responses:
        "200":
          description: IP threat intelligence data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  ip: 8.8.8.8
                  trust_score: 95
                  is_vpn: false
                  is_tor: false
                  asn: AS15169
                  country: US
                  org: Google LLC
                meta:
                  timestamp: "2024-01-15T10:30:00.000Z"
                  processing_time_ms: 125
                correlationId: req-123456789
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /ip-intelligence/batch:
    post:
      tags:
        - IP Intelligence
      operationId: ipIntelligenceBatch
      summary: Batch IP threat intelligence lookup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ips
              properties:
                ips:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  example:
                    - 8.8.8.8
                    - 1.1.1.1
            example:
              ip:
                - 8.8.8.8
                - 1.1.1.1
                - 192.168.1.1
      responses:
        "200":
          description: Threat intelligence for each IP
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  summary:
                    total_requested: 3
                    valid_ips: 3
                    invalid_ips: 0
                    found: 2
                    not_found: 1
                    errors: 0
                  results:
                    - ip: 8.8.8.8
                      found: true
                      data:
                        trust_score: 95
                        is_vpn: false
                        is_tor: false
                meta:
                  processing_time_ms: 125
                  batch_size_range: small
                correlationId: req-123456789
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /profanity/filter:
    get:
      tags:
        - Profanity
      operationId: profanityFilter
      summary: Filter profanity from text
      description: Replaces profane words with asterisks. Returns cleaned text.
      parameters:
        - name: text
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Filtered text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                original: what a damn mess
                filtered: what a **** mess
                matches: 1
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /profanity/detect:
    get:
      tags:
        - Profanity
      operationId: profanityDetect
      summary: Detect whether text contains profanity
      parameters:
        - name: text
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Detection result (contains, word count)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                text: what a damn mess
                hasProfanity: true
                severity: mild
                matchCount: 1
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /profanity/analyze:
    get:
      tags:
        - Profanity
      operationId: profanityAnalyze
      summary: Comprehensive profanity analysis with severity and word positions
      parameters:
        - name: text
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Detailed analysis with severity score, word positions, and categories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  text: What a fucking amazing result!
                  hasProfanity: true
                  severity: high
                  count: 1
                  positions:
                    - start: 7
                      end: 14
                      word: fucking
                      category: strong_language
                  analysis:
                    overallSeverity: high
                    categories:
                      - strong_language
                    context: expressive
                meta:
                  tier: 3
                  correlationId: mno345-pqr678
                  timestamp: "2026-04-06T00:00:00.000Z"
                  processingTime: 25ms
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /sample-data/batch:
    get:
      tags:
        - Sample Data
      operationId: sampleDataBatchGet
      summary: Generate multiple types of sample data (GET)
      description: >
        Generates mock data using Faker.js. Supports 20+ schema types including user, person, address, company, product,
        and more. Use the requests parameter as a JSON-encoded array.
      parameters:
        - name: requests
          in: query
          required: true
          description: JSON-encoded array of generation requests [{type, count, fields?}]
          schema:
            type: string
            example: "[{\"type\":\"user\",\"count\":5}]"
      responses:
        "200":
          description: Generated data records
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                results:
                  - type: user
                    count: 3
                    data:
                      - name: Ada Lovelace
                        email: ada@example.com
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
    post:
      tags:
        - Sample Data
      operationId: sampleDataBatchPost
      summary: Generate multiple types of sample data (POST)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - requests
              properties:
                requests:
                  type: array
                  items:
                    type: object
                    required:
                      - type
                      - count
                    properties:
                      type:
                        type: string
                        description: Schema type (user, person, address, company, product, etc.)
                        example: user
                      count:
                        type: integer
                        minimum: 1
                        maximum: 1000
                        example: 10
                      fields:
                        type: array
                        items:
                          type: string
                        description: Specific fields to include. Returns all fields if omitted.
            example:
              requests:
                - type: user
                  count: 10
                - type: company
                  count: 5
      responses:
        "200":
          description: Generated data records
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                results:
                  - type: user
                    count: 10
                    data:
                      - name: Ada Lovelace
                        email: ada@example.com
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /unit-conversion/convert:
    get:
      tags:
        - Unit Conversion
      operationId: unitConvertGet
      summary: Convert a value between units
      description: >
        Supports 100+ unit types across length, weight, temperature, volume, area, speed, digital storage, and time.
        Converts value from source unit to target unit.
      parameters:
        - name: from
          in: query
          required: true
          description: Source unit identifier (e.g. kg, lb, m, degC, km/h)
          schema:
            type: string
            example: kg
        - name: to
          in: query
          required: true
          description: Target unit identifier
          schema:
            type: string
            example: lb
        - name: value
          in: query
          required: true
          schema:
            type: number
            example: 10
        - name: precision
          in: query
          required: false
          description: Decimal places in result (0-15)
          schema:
            type: integer
            minimum: 0
            maximum: 15
            default: 4
      responses:
        "200":
          description: Conversion result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  original:
                    value: 100
                    unit: meters
                    category: length
                  converted:
                    value: 328.084
                    unit: feet
                    category: length
                  conversion_factor: 3.28084
                  precision: 6
                meta:
                  correlation_id: conv_abc123
                  processing_time: 5ms
                  timestamp: "2026-04-06T00:00:00.000Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
    post:
      tags:
        - Unit Conversion
      operationId: unitConvertPost
      summary: Convert a value between units (POST)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - from
                - to
                - value
              properties:
                from:
                  type: string
                  example: kg
                to:
                  type: string
                  example: lb
                value:
                  type: number
                  example: 10
                precision:
                  type: integer
                  minimum: 0
                  maximum: 15
            example:
              value: 100
              from: meters
              to: feet
              precision: 2
      responses:
        "200":
          description: Conversion result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  original:
                    value: 100
                    unit: meters
                    category: length
                  converted:
                    value: 328.084
                    unit: feet
                    category: length
                  conversion_factor: 3.28084
                  precision: 6
                meta:
                  correlation_id: conv_abc123
                  processing_time: 5ms
                  timestamp: "2026-04-06T00:00:00.000Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /unit-conversion/categories:
    get:
      tags:
        - Unit Conversion
      operationId: unitCategories
      summary: List available measurement categories
      responses:
        "200":
          description: Category list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                categories:
                  - length
                  - mass
                  - temperature
                  - area
                  - volume
                  - speed
                  - time
                  - data
                count: 8
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /unit-conversion/units/{category}:
    get:
      tags:
        - Unit Conversion
      operationId: unitsByCategory
      summary: List units available in a category
      parameters:
        - name: category
          in: path
          required: true
          description: Measurement category (e.g. length, weight, temperature)
          schema:
            type: string
            example: length
      responses:
        "200":
          description: Unit list for the category
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                category: length
                units:
                  - meters
                  - feet
                  - miles
                  - kilometers
                  - inches
                  - centimeters
                  - yards
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /user-avatar:
    get:
      tags:
        - User Avatar
      operationId: userAvatarGenerate
      summary: Generate a customizable user avatar image
      description: >
        Creates avatar images using Canvas (PNG/WebP) or native SVG. Supports initials-based avatars, custom colors,
        external image integration, and uploaded icons.
      parameters:
        - name: name
          in: query
          required: false
          description: Display name to generate initials from
          schema:
            type: string
            example: John Doe
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum:
              - png
              - webp
              - svg
            default: png
        - name: size
          in: query
          required: false
          description: Avatar size in pixels (16–512)
          schema:
            type: integer
            minimum: 16
            maximum: 512
            default: 128
        - name: background
          in: query
          required: false
          description: Background color hex without
          schema:
            type: string
            pattern: ^[0-9A-Fa-f]{6}$
            example: 4A90D9
        - name: color
          in: query
          required: false
          description: Text/icon color hex without
          schema:
            type: string
            pattern: ^[0-9A-Fa-f]{6}$
            example: FFFFFF
        - name: rounded
          in: query
          required: false
          description: Output a circular avatar
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Avatar image binary or SVG markup
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /user-avatar/upload-icon:
    post:
      tags:
        - User Avatar
      operationId: userAvatarUploadIcon
      summary: Upload a custom icon for avatar generation
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Icon image file (PNG, SVG, or WebP, max 1MB)
      responses:
        "200":
          description: Upload confirmation with icon ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                url: https://datpaq.com/avatars/abc123.png
                id: abc123
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /validate-ip/validate:
    get:
      tags:
        - Validate IP
      operationId: validateIpGet
      summary: Validate and classify IP addresses
      description: >
        Validates IPv4, IPv6, or CIDR notation and returns classification flags: private, reserved, loopback, multicast,
        link-local, bogon, and public. Supports comma-separated batch input (max 100).
      parameters:
        - name: ip
          in: query
          required: true
          description: Single IP, CIDR notation, or comma-separated list (max 100)
          schema:
            type: string
            example: 8.8.8.8
      responses:
        "200":
          description: Validation and classification results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                ip: 192.168.1.1
                valid: true
                type: IPv4
                cidr: false
                private: true
                reserved: false
                loopback: false
                multicast: false
                link_local: false
                bogon: false
                message: Valid IPv4 address
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
    post:
      tags:
        - Validate IP
      operationId: validateIpPost
      summary: Validate and classify IP addresses (POST)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ip
              properties:
                ip:
                  description: Single IP string or array of IPs
                  oneOf:
                    - type: string
                      example: 8.8.8.8
                    - type: array
                      items:
                        type: string
                      maxItems: 100
            example:
              ip:
                - 8.8.8.8
                - 127.0.0.1
                - 192.168.1.0/24
      responses:
        "200":
          description: Validation results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                - ip: 8.8.8.8
                  valid: true
                  type: IPv4
                  private: false
                - ip: 127.0.0.1
                  valid: true
                  type: IPv4
                  loopback: true
                - ip: 192.168.1.0/24
                  valid: true
                  type: IPv4
                  cidr: true
                  private: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /web-screenshot:
    get:
      tags:
        - Web Screenshot
      operationId: webScreenshot
      summary: Capture a screenshot of a web page
      description: >
        Renders a web page via Puppeteer headless browser and returns a screenshot. Supports viewport simulation, format
        selection, quality control, and crop.
      parameters:
        - name: url
          in: query
          required: true
          description: Target URL including http/https scheme
          schema:
            type: string
            format: uri
            example: https://example.com
        - name: width
          in: query
          required: false
          description: Viewport width in pixels (100–3840, default 1280)
          schema:
            type: integer
            minimum: 100
            maximum: 3840
            default: 1280
        - name: height
          in: query
          required: false
          description: Viewport height in pixels (100–2160, default 800)
          schema:
            type: integer
            minimum: 100
            maximum: 2160
            default: 800
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum:
              - jpeg
              - png
              - webp
            default: jpeg
        - name: quality
          in: query
          required: false
          description: Image quality (10–100, default 100; ignored for PNG)
          schema:
            type: integer
            minimum: 10
            maximum: 100
            default: 100
        - name: crop
          in: query
          required: false
          description: Crop dimensions as WIDTHxHEIGHT (e.g. 800x600)
          schema:
            type: string
            example: 800x600
      responses:
        "200":
          description: Screenshot image binary
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /whois/lookup:
    post:
      tags:
        - WHOIS
      operationId: whoisLookup
      summary: Perform WHOIS lookup for one or multiple domains
      description: >
        Returns registrar, registration date, expiration date, name servers, and raw WHOIS data. Supports single domain
        or batch array (max 50).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  description: Single domain string or array (max 50)
                  oneOf:
                    - type: string
                      example: example.com
                    - type: array
                      items:
                        type: string
                      maxItems: 50
            example:
              domain: datpaq.com
      responses:
        "200":
          description: WHOIS registration data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                fromCache: false
                domain: datpaq.com
                tld: com
                tldType: generic
                category: commercial
                registrar: Example Registrar Inc.
                creationDate: "1995-08-14T04:00:00.000Z"
                expirationDate: "2024-08-13T04:00:00.000Z"
                nameServers:
                  - a.iana-servers.net
                  - b.iana-servers.net
                raw: "Domain Name: EXAMPLE.COM..."
                registrantRedacted: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /working-days/calculate:
    post:
      tags:
        - Working Days
      operationId: workingDaysCalculatePost
      summary: Calculate working days between dates or offset business days
      description: >
        For range calculations: provide start_date and end_date to get the number of working days between them. For
        offset calculations: provide start_date and days_offset to find the resulting business date. Supports US, DE,
        and IN regional holiday calendars.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - start_date
              properties:
                start_date:
                  type: string
                  format: date
                  example: "2026-01-01"
                end_date:
                  type: string
                  format: date
                  example: "2026-01-31"
                days_offset:
                  type: integer
                  description: Working days to add (positive) or subtract (negative)
                  example: 10
                direction:
                  type: string
                  enum:
                    - forward
                    - backward
                  default: forward
                region:
                  type: string
                  description: Regional holiday calendar
                  enum:
                    - US
                    - DE
                    - IN
                  default: US
            example:
              start_date: "2026-07-01"
              end_date: "2026-07-15"
              region: US
      responses:
        "200":
          description: Working day calculation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  working_days: 8
                  start_date: "2025-07-01"
                  end_date: "2025-07-15"
                  region: US
                  holidays_used:
                    - "2025-07-04"
                meta:
                  batchSize: 1
                  successCount: 1
                  errorCount: 0
                  processingTimeMs: 15
                  timestamp: "2025-12-10T15:30:00.000Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
    get:
      tags:
        - Working Days
      operationId: workingDaysCalculateGet
      summary: Calculate working days (GET)
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
            example: "2026-01-01"
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
        - name: days_offset
          in: query
          required: false
          schema:
            type: integer
        - name: region
          in: query
          required: false
          schema:
            type: string
            enum:
              - US
              - DE
              - IN
            default: US
      responses:
        "200":
          description: Working day calculation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  working_days: 8
                  start_date: "2025-07-01"
                  end_date: "2025-07-15"
                  region: US
                  holidays_used:
                    - "2025-07-04"
                meta:
                  batchSize: 1
                  successCount: 1
                  errorCount: 0
                  processingTimeMs: 15
                  timestamp: "2025-12-10T15:30:00.000Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /working-days/calculate/batch:
    get:
      tags:
        - Working Days
      operationId: workingDaysBatch
      summary: Batch working day calculations
      parameters:
        - name: requests
          in: query
          required: true
          description: JSON-encoded array of calculation requests
          schema:
            type: string
            example: "[{\"start_date\":\"2026-01-01\",\"end_date\":\"2026-01-31\"}]"
      responses:
        "200":
          description: Batch calculation results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                data:
                  - working_days: 8
                    start_date: "2025-07-01"
                    end_date: "2025-07-15"
                    region: US
                    holidays_used:
                      - "2025-07-04"
                  - working_days: 7
                    start_date: "2025-08-01"
                    end_date: "2025-07-21"
                    region: US
                    holidays_used: []
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /generate:
    post:
      tags:
        - Sample Data
      operationId: sampleDataGeneratePost
      summary: Generate sample data
      description: >-
        Generate realistic mock data using a JSON request body. Recommended for full control over type, count, fields,
        and format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  description: Schema type to generate, such as user, company, product, or transaction.
                count:
                  type: integer
                  minimum: 1
                  maximum: 10000
                  default: 1
                fields:
                  type: array
                  items:
                    type: string
                  description: Optional field names to include.
                format:
                  type: string
                  enum:
                    - json
                    - csv
                  default: json
            example:
              type: user
              count: 5
              fields:
                - name
                - email
                - phone
      responses:
        "200":
          description: Generated sample data records
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                type: user
                count: 5
                format: json
                data:
                  - name: John Smith
                    email: john.smith@example.com
                    phone: +1-555-123-4567
                correlationId: req_abc123
                timestamp: "2026-04-06T00:00:00.000Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /generate-batch:
    post:
      tags:
        - Sample Data
      operationId: sampleDataGenerateBatchPost
      summary: Generate multiple sample datasets
      description: Submit multiple sample-data generation requests in one call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - requests
              properties:
                requests:
                  type: array
                  maxItems: 10
                  items:
                    type: object
                    required:
                      - type
                    properties:
                      type:
                        type: string
                      count:
                        type: integer
                        minimum: 1
                        maximum: 1000
                        default: 1
                      fields:
                        type: array
                        items:
                          type: string
                      format:
                        type: string
                        enum:
                          - json
                          - csv
                        default: json
            example:
              requests:
                - type: user
                  count: 10
                - type: company
                  count: 5
      responses:
        "200":
          description: Generated data records grouped by request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                results:
                  - type: user
                    count: 2
                    data:
                      - name: Ada Lovelace
                        email: ada@example.com
                  - type: company
                    count: 1
                    data:
                      - name: Globex
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /sample-data:
    get:
      tags:
        - Sample Data
      operationId: sampleDataGenerateGet
      summary: Generate sample data with query parameters
      description: GET-compatible sample data generation endpoint for scripts and browser testing.
      parameters:
        - name: type
          in: query
          required: true
          description: Schema type to generate, such as user, company, product, or transaction.
          schema:
            type: string
        - name: count
          in: query
          required: false
          description: Number of records to generate.
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1
        - name: fields
          in: query
          required: false
          description: Comma-separated list of fields to include.
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum:
              - json
              - csv
            default: json
      responses:
        "200":
          description: Generated sample data records
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                type: user
                count: 5
                format: json
                data:
                  - name: John Smith
                    email: john.smith@example.com
                    phone: +1-555-123-4567
                correlationId: req_abc123
                timestamp: "2026-04-06T00:00:00.000Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /schemas:
    get:
      tags:
        - Sample Data
      operationId: sampleDataSchemas
      summary: List sample data schemas
      description: Returns all available sample-data schema names with default field lists.
      responses:
        "200":
          description: Available sample-data schemas
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                schemas:
                  - user
                  - company
                  - product
                  - transaction
                  - address
                count: 5
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /ip-intelligence/batch/info:
    get:
      tags:
        - IP Intelligence
      operationId: ipIntelligenceBatchInfo
      summary: Get IP intelligence batch configuration
      description: Returns batch processing limits, example request shape, and response schema details.
      responses:
        "200":
          description: Batch processing configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                maxBatchSize: 100
                supportedFormats:
                  - ipv4
                  - ipv6
                rateLimit: per-key
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
  /image-processing:
    get:
      tags:
        - Image Processing
      operationId: imageProcessingInfo
      summary: Get image processing service information
      description: Returns supported image operations, formats, and service metadata.
      responses:
        "200":
          description: Image processing service information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericSuccess"
              example:
                success: true
                operations:
                  - resize
                  - compress
                  - convert
                  - crop
                  - metadata
                  - process
                maxFileSize: 10MB
                supportedFormats:
                  - jpeg
                  - png
                  - webp
                  - avif
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/ServiceUnavailable"
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key passed via x-api-key request header
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as api_key query parameter
  responses:
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Unauthorized — missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimited:
      description: Rate limit exceeded — retry after the indicated period
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ServiceUnavailable:
      description: Service temporarily unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Invalid API key
        correlationId:
          type: string
          description: Request tracking identifier for support
          example: abc123-def456-789ghi
        service:
          type: string
          description: Service name that produced the error
          example: ip-geolocation
    GenericSuccess:
      type: object
      description: Standard success envelope. The data property structure varies by endpoint.
      properties:
        correlationId:
          type: string
          description: Request tracking identifier
          example: abc123-def456
        data:
          type: object
          description: Response payload (structure varies by endpoint)
        cached:
          type: boolean
          description: Whether the response was served from cache
          example: false
    BlogAuthor:
      type: object
      properties:
        name:
          type: string
          example: DATPAQ Team
        position:
          type: string
          nullable: true
          example: Product
    BlogCategory:
      type: object
      properties:
        name:
          type: string
          example: Blog
        slug:
          type: string
          enum:
            - all
            - press-release
            - news
            - blog
          example: blog
    BlogPagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 10
        totalItems:
          type: integer
          example: 42
        totalPages:
          type: integer
          example: 5
    BlogPostSummary:
      type: object
      properties:
        id:
          type: string
          example: clx123example
        title:
          type: string
          example: DATPAQ launches new API tools
        slug:
          type: string
          example: datpaq-launches-new-api-tools
        excerpt:
          type: string
          example: A quick look at the latest DATPAQ platform updates.
        url:
          type: string
          format: uri
          example: https://datpaq.com/blog/datpaq-launches-new-api-tools
        publishedAt:
          type: string
          format: date-time
          nullable: true
        author:
          $ref: "#/components/schemas/BlogAuthor"
        category:
          $ref: "#/components/schemas/BlogCategory"
        tags:
          type: array
          items:
            type: string
          example:
            - product
            - api
    BlogPostDetail:
      allOf:
        - $ref: "#/components/schemas/BlogPostSummary"
        - type: object
          properties:
            html:
              type: string
              description: Rendered HTML body for display clients.
              example: <p>A quick look at the latest DATPAQ platform updates.</p>
            plainText:
              type: string
              description: Plain text body for terminal, CLI, and MCP clients.
              example: A quick look at the latest DATPAQ platform updates.
    BlogPostListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/BlogPostSummary"
        pagination:
          $ref: "#/components/schemas/BlogPagination"
    BlogPostDetailResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/BlogPostDetail"