{
  "openapi": "3.1.0",
  "info": {
    "title": "LOOKUP API",
    "description": "Ultra-low latency SHA-256 reverse lookup infrastructure for 100M+ Kenyan mobile records (254XXXXXXXXX).",
    "version": "2026-09-12"
  },
  "servers": [
    {
      "url": "https://backend.zero-one-logistics.co.ke",
      "description": "Production Ingress"
    }
  ],
  "paths": {
    "/v1/lookup/{sha256}": {
      "get": {
        "summary": "Single SHA-256 Reverse Lookup",
        "operationId": "reverseLookup",
        "description": "Resolve a 64-character lowercase SHA-256 hex string to its verified Kenyan phone number in ~0.5ms.",
        "parameters": [
          {
            "name": "sha256",
            "in": "path",
            "required": true,
            "description": "64-character hexadecimal SHA-256 hash",
            "schema": {
              "type": "string",
              "pattern": "^[a-fA-F0-9]{64}$",
              "example": "1235926f0e31f4c9cee58f172167753b2f94f7574fb89f7adfcbb8724fa0446c"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Hash successfully resolved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "number": { "type": "string", "example": "254791000000" }
                  },
                  "required": ["number"]
                }
              }
            }
          },
          "404": {
            "description": "Hash not found in dataset"
          },
          "429": {
            "description": "Rate limit or quota exceeded"
          }
        }
      }
    },
    "/v1/lookup/batch": {
      "post": {
        "summary": "Synchronous Batch Reverse Lookup",
        "operationId": "batchLookup",
        "description": "Synchronously resolve up to 500 SHA-256 hashes in a single call.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hashes": {
                    "type": "array",
                    "items": { "type": "string" },
                    "maxItems": 500
                  }
                },
                "required": ["hashes"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch lookup results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_requested": { "type": "integer" },
                    "found_count": { "type": "integer" },
                    "missing_count": { "type": "integer" },
                    "invalid_count": { "type": "integer" },
                    "results": {
                      "type": "object",
                      "additionalProperties": { "type": "string" }
                    },
                    "missing": {
                      "type": "array",
                      "items": { "type": "string" }
                    },
                    "invalid": {
                      "type": "array",
                      "items": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/jobs/batch": {
      "post": {
        "summary": "Submit 50,000-Item Asynchronous Batch Job",
        "operationId": "submitBatchJob",
        "description": "Queue background processing for up to 50,000 hashes with optional webhook notification.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hashes": {
                    "type": "array",
                    "items": { "type": "string" },
                    "maxItems": 50000
                  },
                  "webhook_url": {
                    "type": "string",
                    "format": "uri"
                  }
                },
                "required": ["hashes"]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Job queued successfully"
          }
        }
      }
    },
    "/v1/jobs/{job_id}": {
      "get": {
        "summary": "Poll Asynchronous Job Status",
        "operationId": "getJobStatus",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Job status and progress counters"
          }
        }
      }
    },
    "/v1/jobs/{job_id}/results": {
      "get": {
        "summary": "Fetch Completed Job Results",
        "operationId": "getJobResults",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved dataset dictionary"
          }
        }
      }
    },
    "/v1/hash/{number}": {
      "get": {
        "summary": "Forward Number Hash",
        "operationId": "forwardHash",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "254791000000" }
          }
        ],
        "responses": {
          "200": {
            "description": "Generated SHA-256 digest"
          }
        }
      }
    },
    "/v1/users": {
      "post": {
        "summary": "Self-Service API Key Registration",
        "operationId": "registerUser",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "phone": { "type": "string" },
                  "rate_limit_rps": { "type": "integer", "default": 500 }
                },
                "required": ["username", "email"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created successfully"
          }
        }
      }
    },
    "/v1/users/me": {
      "get": {
        "summary": "Get Profile & Current Quota",
        "operationId": "getMyProfile",
        "responses": {
          "200": {
            "description": "Current user quota and settings"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}