openapi: 3.0.0
info:
  title: Api Ocr Ktp
  description: >-
    Complete API collection for Indonesian KTP (ID card) data extraction. Extract structured KTP data from image files
    (JPG, JPEG, PNG) with automatic field extraction and validation. Maximum file size: 5 MB.
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: KTP Extraction
    description: KTP extraction endpoints for processing Indonesian ID card images.
paths:
  /ocr/ktp-extract:
    post:
      tags:
        - KTP Extraction
      summary: Extract KTP from Image
      description: >-
        Extract structured KTP data from an uploaded image file. Maximum file size: 5 MB.
        Supported formats: JPG, JPEG, PNG. Returns complete KTP data with all extracted fields.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: 'KTP image file. Maximum size: 5 MB. Supported formats: JPG, JPEG, PNG'
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      responses:
        '200':
          description: Success - KTP Extracted
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      nik:
                        type: string
                        description: NIK (16-digit ID number)
                        example: '3201012345678901'
                      nama:
                        type: string
                        description: Full name
                        example: 'JOHN DOE'
                      tempat_lahir:
                        type: string
                        description: Birth place
                        example: 'JAKARTA'
                      tanggal_lahir:
                        type: string
                        description: Birth date (DD-MM-YYYY)
                        example: '01-01-1990'
                      jenis_kelamin:
                        type: string
                        description: Gender (LAKI-LAKI/PEREMPUAN)
                        example: 'LAKI-LAKI'
                      golongan_darah:
                        type: string
                        description: Blood type
                        example: 'O'
                      alamat:
                        type: string
                        description: Address
                        example: 'JL. MERDEKA NO. 123'
                      rt:
                        type: string
                        description: RT (neighborhood unit)
                        example: '001'
                      rw:
                        type: string
                        description: RW (community unit)
                        example: '002'
                      kelurahan:
                        type: string
                        description: Village/Kelurahan
                        example: 'GAMBIR'
                      kecamatan:
                        type: string
                        description: Subdistrict/Kecamatan
                        example: 'GAMBIR'
                      kota:
                        type: string
                        description: City
                        example: 'JAKARTA PUSAT'
                      provinsi:
                        type: string
                        description: Province
                        example: 'DKI JAKARTA'
                      agama:
                        type: string
                        description: Religion
                        example: 'ISLAM'
                      status_perkawinan:
                        type: string
                        description: Marital status
                        example: 'BELUM KAWIN'
                      pekerjaan:
                        type: string
                        description: Occupation
                        example: 'KARYAWAN SWASTA'
                      kewarganegaraan:
                        type: string
                        description: Nationality
                        example: 'WNI'
                      berlaku_hingga:
                        type: string
                        description: Valid until
                        example: 'SEUMUR HIDUP'
              examples:
                success:
                  summary: Success - KTP Extracted
                  value:
                    is_success: true
                    message: Success
                    data:
                      nik: '3201012345678901'
                      nama: 'JOHN DOE'
                      tempat_lahir: 'JAKARTA'
                      tanggal_lahir: '01-01-1990'
                      jenis_kelamin: 'LAKI-LAKI'
                      golongan_darah: 'O'
                      alamat: 'JL. MERDEKA NO. 123'
                      rt: '001'
                      rw: '002'
                      kelurahan: 'GAMBIR'
                      kecamatan: 'GAMBIR'
                      kota: 'JAKARTA PUSAT'
                      provinsi: 'DKI JAKARTA'
                      agama: 'ISLAM'
                      status_perkawinan: 'BELUM KAWIN'
                      pekerjaan: 'KARYAWAN SWASTA'
                      kewarganegaraan: 'WNI'
                      berlaku_hingga: 'SEUMUR HIDUP'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing File:
                  summary: Missing File
                  value:
                    is_success: false
                    message: 'File is required'
                Invalid File Type:
                  summary: Invalid File Type
                  value:
                    is_success: false
                    message: 'Invalid file type. Supported formats: JPG, JPEG, PNG'
                File Too Large:
                  summary: File Too Large
                  value:
                    is_success: false
                    message: 'File size exceeds maximum limit of 5 MB'
                Invalid KTP Image:
                  summary: Invalid KTP Image
                  value:
                    is_success: false
                    message: 'Invalid KTP image. Please provide a valid Indonesian KTP image'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
                Invalid API Key:
                  summary: Invalid API Key
                  value:
                    is_success: false
                    message: 'Invalid API key'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
