openapi: 3.0.3
info:
  title: 'OpenMetaAPI Documentation'
  description: 'Fast, stateless API for URL meta extraction and DNS lookups.'
  version: 1.0.0
servers:
  -
    url: 'https://openmetaapi.syofyanzuhad.dev'
tags:
  -
    name: 'DNS Resolution'
    description: ''
  -
    name: Endpoints
    description: ''
  -
    name: 'Metadata Extraction'
    description: ''
components:
  securitySchemes:
    default:
      type: apiKey
      name: X-API-Key
      in: header
      description: 'You can retrieve your API key from your dashboard.'
security:
  -
    default: []
paths:
  /api/v1/dns:
    get:
      summary: 'Resolve DNS'
      operationId: resolveDNS
      description: "Resolve DNS records for a given domain. Supported types for all users: A, AAAA, MX, CNAME, TXT, NS.\nPro users can also resolve: SOA, PTR, SRV, CAA, ANY."
      parameters:
        -
          in: query
          name: domain
          description: 'The domain name to resolve.'
          example: laravel.com
          required: true
          schema:
            type: string
            description: 'The domain name to resolve.'
            example: laravel.com
        -
          in: query
          name: type
          description: 'The record type. <br/><small class="badge badge-info">SOA, PTR, SRV, CAA, ANY are Pro Only</small>. Default: A.'
          example: MX
          required: false
          schema:
            type: string
            description: 'The record type. <br/><small class="badge badge-info">SOA, PTR, SRV, CAA, ANY are Pro Only</small>. Default: A.'
            example: MX
        -
          in: header
          name: X-API-Key
          description: ''
          example: '{YOUR_API_KEY}'
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    domain: laravel.com
                    type: MX
                    records:
                      -
                        host: laravel.com
                        class: IN
                        ttl: 300
                        type: MX
                        pri: 1
                        target: aspmx.l.google.com
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      domain:
                        type: string
                        example: laravel.com
                      type:
                        type: string
                        example: MX
                      records:
                        type: array
                        example:
                          -
                            host: laravel.com
                            class: IN
                            ttl: 300
                            type: MX
                            pri: 1
                            target: aspmx.l.google.com
                        items:
                          type: object
                          properties:
                            host:
                              type: string
                              example: laravel.com
                            class:
                              type: string
                              example: IN
                            ttl:
                              type: integer
                              example: 300
                            type:
                              type: string
                              example: MX
                            pri:
                              type: integer
                              example: 1
                            target:
                              type: string
                              example: aspmx.l.google.com
      tags:
        - 'DNS Resolution'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  type: string
                  description: 'Must match the regex /^(?!:\/\/)(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}$/.'
                  example: '!://):8hE.):EkR.)k{2,}'
                type:
                  type: string
                  description: ''
                  example: PTR
                  enum:
                    - A
                    - AAAA
                    - CNAME
                    - MX
                    - TXT
                    - NS
                    - SOA
                    - PTR
                    - SRV
                    - CAA
                    - ANY
                  nullable: true
              required:
                - domain
  /api/v1/internal/benchmark:
    get:
      summary: 'Handle the incoming request for stress testing.'
      operationId: handleTheIncomingRequestForStressTesting
      description: 'This endpoint is optimized for high-throughput testing.'
      parameters:
        -
          in: header
          name: X-API-Key
          description: ''
          example: '{YOUR_API_KEY}'
          schema:
            type: string
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Unauthorized: Invalid API Key Format'
                properties:
                  message:
                    type: string
                    example: 'Unauthorized: Invalid API Key Format'
      tags:
        - Endpoints
  /api/v1/meta:
    get:
      summary: 'Extract Metadata'
      operationId: extractMetadata
      description: "Extract comprehensive metadata from any public URL, including Title, Description, Favicon, Open Graph, and Twitter Cards.\nPro users also receive JSON-LD, Keywords, Author, Canonical URL, Language, and Performance Metrics."
      parameters:
        -
          in: query
          name: url
          description: 'The URL to extract metadata from.'
          example: 'https://laravel.com'
          required: true
          schema:
            type: string
            description: 'The URL to extract metadata from.'
            example: 'https://laravel.com'
        -
          in: query
          name: force
          description: 'Bypass cache and force a fresh extraction. <br/><small class="badge badge-info">Pro Only</small>'
          example: false
          required: false
          schema:
            type: boolean
            description: 'Bypass cache and force a fresh extraction. <br/><small class="badge badge-info">Pro Only</small>'
            example: false
        -
          in: header
          name: X-API-Key
          description: ''
          example: '{YOUR_API_KEY}'
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: ''
                    type: object
                    example:
                      success: true
                      data:
                        url: 'https://laravel.com'
                        meta:
                          title: 'Laravel - The PHP Framework For Web Artisans'
                          description: 'Laravel is a web application framework with expressive, elegant syntax...'
                          favicon: 'https://laravel.com/favicon.ico'
                          open_graph:
                            'og:title': Laravel
                            'og:description': ...
                          twitter_card:
                            'twitter:card': summary_large_image
                    properties:
                      success:
                        type: boolean
                        example: true
                      data:
                        type: object
                        properties:
                          url:
                            type: string
                            example: 'https://laravel.com'
                          meta:
                            type: object
                            properties:
                              title:
                                type: string
                                example: 'Laravel - The PHP Framework For Web Artisans'
                              description:
                                type: string
                                example: 'Laravel is a web application framework with expressive, elegant syntax...'
                              favicon:
                                type: string
                                example: 'https://laravel.com/favicon.ico'
                              open_graph:
                                type: object
                                properties:
                                  'og:title':
                                    type: string
                                    example: Laravel
                                  'og:description':
                                    type: string
                                    example: ...
                              twitter_card:
                                type: object
                                properties:
                                  'twitter:card':
                                    type: string
                                    example: summary_large_image
                  -
                    description: 'Pro User'
                    type: object
                    example:
                      success: true
                      data:
                        url: 'https://laravel.com'
                        meta:
                          title: Laravel
                          description: ...
                          favicon: ...
                          open_graph: {  }
                          twitter_card: {  }
                          author: 'Taylor Otwell'
                          keywords:
                            - php
                            - framework
                          canonical: 'https://laravel.com/'
                          lang: en
                          robots: 'index, follow'
                          json_ld: []
                          metrics:
                            fetch_duration_ms: 150.5
                            http_status: 200
                    properties:
                      success:
                        type: boolean
                        example: true
                      data:
                        type: object
                        properties:
                          url:
                            type: string
                            example: 'https://laravel.com'
                          meta:
                            type: object
                            properties:
                              title:
                                type: string
                                example: Laravel
                              description:
                                type: string
                                example: ...
                              favicon:
                                type: string
                                example: ...
                              open_graph:
                                type: object
                                properties: {  }
                              twitter_card:
                                type: object
                                properties: {  }
                              author:
                                type: string
                                example: 'Taylor Otwell'
                              keywords:
                                type: array
                                example:
                                  - php
                                  - framework
                                items:
                                  type: string
                              canonical:
                                type: string
                                example: 'https://laravel.com/'
                              lang:
                                type: string
                                example: en
                              robots:
                                type: string
                                example: 'index, follow'
                              json_ld:
                                type: array
                                example: []
                              metrics:
                                type: object
                                properties:
                                  fetch_duration_ms:
                                    type: number
                                    example: 150.5
                                  http_status:
                                    type: integer
                                    example: 200
      tags:
        - 'Metadata Extraction'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: 'Must be a valid URL. Must not be greater than 2048 characters.'
                  example: 'http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html'
                force:
                  type: boolean
                  description: ''
                  example: false
                  nullable: true
              required:
                - url