{"openapi":"3.1.0","info":{"title":"world-id-gateway","description":"","license":{"name":"MIT","identifier":"MIT"},"version":"0.1.4"},"paths":{"/cancel-recovery-agent-update":{"post":{"tags":["Gateway"],"operationId":"_doc_cancel_recovery_agent_update","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRecoveryAgentUpdateRequest"}}},"required":true},"responses":{"200":{"description":"Request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/create-account":{"post":{"tags":["Gateway"],"operationId":"_doc_create_account","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountRequest"}}},"required":true},"responses":{"202":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"500":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/execute-recovery-agent-update":{"post":{"tags":["Gateway"],"operationId":"_doc_execute_recovery_agent_update","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteRecoveryAgentUpdateRequest"}}},"required":true},"responses":{"200":{"description":"Request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"400":{"description":"Bad request (leaf_index zero or no pending update)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/health":{"get":{"tags":["Gateway"],"operationId":"health","responses":{"200":{"description":"General status check for the server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/initiate-recovery-agent-update":{"post":{"tags":["Gateway"],"operationId":"_doc_initiate_recovery_agent_update","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRecoveryAgentRequest"}}},"required":true},"responses":{"200":{"description":"Request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/insert-authenticator":{"post":{"tags":["Gateway"],"operationId":"_doc_insert_authenticator","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertAuthenticatorRequest"}}},"required":true},"responses":{"202":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"500":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/is-valid-root":{"get":{"tags":["Gateway"],"operationId":"_doc_is_valid_root","parameters":[{"name":"root","in":"path","description":"Root to validate (hex string).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IsValidRootResponse"}}}},"400":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/recover-account":{"post":{"tags":["Gateway"],"operationId":"_doc_recover_account","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoverAccountRequest"}}},"required":true},"responses":{"202":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"500":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/remove-authenticator":{"post":{"tags":["Gateway"],"operationId":"_doc_remove_authenticator","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveAuthenticatorRequest"}}},"required":true},"responses":{"202":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"500":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/status/{id}":{"get":{"tags":["Gateway"],"operationId":"_doc_request_status","parameters":[{"name":"id","in":"path","description":"TODO","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"404":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}},"/update-authenticator":{"post":{"tags":["Gateway"],"operationId":"_doc_update_authenticator","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAuthenticatorRequest"}}},"required":true},"responses":{"202":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayStatusResponse"}}}},"500":{"description":"TODO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceApiError"}}}}}}}},"components":{"schemas":{"CancelRecoveryAgentUpdateRequest":{"type":"object","description":"The request to cancel a pending recovery agent update.\n\nNumeric string fields in this request accept decimal or `0x`/`0X`-prefixed hex.","required":["leaf_index","signature","nonce"],"properties":{"leaf_index":{"type":"string","format":"hex","description":"The account index."},"nonce":{"type":"string","format":"hex","description":"The nonce."},"signature":{"type":"string","format":"hex","description":"The signature."}}},"CreateAccountRequest":{"type":"object","description":"The request to create a new World ID account.\n\nNumeric string fields in this request accept decimal or `0x`/`0X`-prefixed hex.","required":["recovery_address","authenticator_addresses","authenticator_pubkeys","offchain_signer_commitment"],"properties":{"authenticator_addresses":{"type":"array","items":{"type":"string","format":"hex"},"description":"The addresses of the authenticators."},"authenticator_pubkeys":{"type":"array","items":{"type":"string","format":"hex"},"description":"The compressed public keys of the authenticators."},"offchain_signer_commitment":{"type":"string","format":"hex","description":"The offchain signer commitment."},"recovery_address":{"type":"string","format":"hex","description":"The recovery address."}}},"ExecuteRecoveryAgentUpdateRequest":{"type":"object","description":"The request to execute a pending recovery agent update.\n\nNo signature is required — `executeRecoveryAgentUpdate` is permissionless.\nThe contract enforces the 14-day cooldown and will revert with\n`RecoveryAgentUpdateStillInCooldown` if called too early.\n\nNumeric string fields in this request accept decimal or `0x`/`0X`-prefixed hex.","required":["leaf_index"],"properties":{"leaf_index":{"type":"string","format":"hex","description":"The account index."}}},"GatewayErrorCode":{"type":"string","description":"Gateway error codes.","enum":["internal_server_error","not_found","bad_request","batcher_unavailable","authenticator_already_exists","authenticator_does_not_exist","mismatched_signature_nonce","pubkey_id_in_use","pubkey_id_out_of_bounds","authenticator_does_not_belong_to_account","transaction_reverted","confirmation_error","duplicate_request_in_flight","rate_limit_exceeded","request_timeout","method_not_available"]},"GatewayRequestId":{"type":"string","description":"Strongly-typed identifier for a gateway request.\n\nReturned by gateway mutation endpoints (create-account, insert/update/remove\nauthenticator, etc.) and used to poll the status of the request."},"GatewayRequestKind":{"type":"string","description":"Kind of request tracked by the registry gateway.","enum":["create_account","update_authenticator","insert_authenticator","remove_authenticator","update_recovery_agent","cancel_recovery_agent_update","execute_recovery_agent_update","recover_account"]},"GatewayRequestState":{"oneOf":[{"type":"object","description":"Request queued but not yet batched.","required":["state"],"properties":{"state":{"type":"string","enum":["queued"]}}},{"type":"object","description":"Request currently being batched.","required":["state"],"properties":{"state":{"type":"string","enum":["batching"]}}},{"type":"object","description":"Request submitted on-chain, hash available.","required":["tx_hash","state"],"properties":{"state":{"type":"string","enum":["submitted"]},"tx_hash":{"type":"string","description":"Transaction hash emitted when the request was submitted."}}},{"type":"object","description":"Request finalized on-chain.","required":["tx_hash","state"],"properties":{"state":{"type":"string","enum":["finalized"]},"tx_hash":{"type":"string","description":"Transaction hash emitted when the request was finalized."}}},{"type":"object","description":"Request failed during processing.","required":["error","state"],"properties":{"error":{"type":"string","description":"Error message returned by the gateway."},"error_code":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/GatewayErrorCode","description":"Specific error code, if available."}]},"state":{"type":"string","enum":["failed"]}}}],"description":"Tracking state for a registry gateway request."},"GatewayStatusResponse":{"type":"object","description":"Response returned by the registry gateway for state-changing requests.","required":["request_id","kind","status"],"properties":{"kind":{"$ref":"#/components/schemas/GatewayRequestKind","description":"The kind of operation that was submitted."},"request_id":{"$ref":"#/components/schemas/GatewayRequestId","description":"Identifier assigned by the gateway to the submitted request."},"status":{"$ref":"#/components/schemas/GatewayRequestState","description":"The current state of the request."}}},"HealthResponse":{"type":"object","description":"Health response for an API service (gateway or indexer).","required":["success"],"properties":{"success":{"type":"boolean","description":"Success value."}}},"InsertAuthenticatorRequest":{"type":"object","description":"The request to insert an authenticator.\n\nNumeric string fields in this request accept decimal or `0x`/`0X`-prefixed hex.","required":["leaf_index","new_authenticator_address","old_offchain_signer_commitment","new_offchain_signer_commitment","signature","nonce","pubkey_id","new_authenticator_pubkey"],"properties":{"leaf_index":{"type":"string","format":"hex","description":"The account index."},"new_authenticator_address":{"type":"string","format":"hex","description":"The new authenticator address."},"new_authenticator_pubkey":{"type":"string","format":"hex","description":"The new authenticator pubkey."},"new_offchain_signer_commitment":{"type":"string","format":"hex","description":"The new offchain signer commitment."},"nonce":{"type":"string","format":"hex","description":"The nonce."},"old_offchain_signer_commitment":{"type":"string","format":"hex","description":"The old offchain signer commitment."},"pubkey_id":{"type":"string","format":"hex","description":"The pubkey id."},"signature":{"type":"string","format":"hex","description":"The signature."}}},"IsValidRootQuery":{"type":"object","description":"Query params for the `/is-valid-root` endpoint.","required":["root"],"properties":{"root":{"type":"string","format":"hex","description":"Root to validate (hex string)."}}},"IsValidRootResponse":{"type":"object","description":"Response payload for root validity checks.","required":["valid"],"properties":{"valid":{"type":"boolean","description":"Whether the root is currently valid on-chain."}}},"RecoverAccountRequest":{"type":"object","description":"The request to recover an account.\n\nNumeric string fields in this request accept decimal or `0x`/`0X`-prefixed hex.","required":["leaf_index","new_authenticator_address","old_offchain_signer_commitment","new_offchain_signer_commitment","signature","nonce"],"properties":{"leaf_index":{"type":"string","format":"hex","description":"The account index."},"new_authenticator_address":{"type":"string","format":"hex","description":"The new authenticator address."},"new_authenticator_pubkey":{"type":["string","null"],"format":"hex","description":"The new authenticator pubkey."},"new_offchain_signer_commitment":{"type":"string","format":"hex","description":"The new offchain signer commitment."},"nonce":{"type":"string","format":"hex","description":"The nonce."},"old_offchain_signer_commitment":{"type":"string","format":"hex","description":"The old offchain signer commitment."},"signature":{"type":"string","format":"hex","description":"The signature."}}},"RemoveAuthenticatorRequest":{"type":"object","description":"The request to remove an authenticator.\n\nNumeric string fields in this request accept decimal or `0x`/`0X`-prefixed hex.","required":["leaf_index","authenticator_address","old_offchain_signer_commitment","new_offchain_signer_commitment","signature","nonce"],"properties":{"authenticator_address":{"type":"string","format":"hex","description":"The authenticator address."},"authenticator_pubkey":{"type":["string","null"],"format":"hex","description":"The authenticator pubkey."},"leaf_index":{"type":"string","format":"hex","description":"The account index."},"new_offchain_signer_commitment":{"type":"string","format":"hex","description":"The new offchain signer commitment."},"nonce":{"type":"string","format":"hex","description":"The nonce."},"old_offchain_signer_commitment":{"type":"string","format":"hex","description":"The old offchain signer commitment."},"pubkey_id":{"type":["string","null"],"format":"hex","description":"The pubkey id."},"signature":{"type":"string","format":"hex","description":"The signature."}}},"ServiceApiError":{"type":"object","description":"Error object returned by the services APIs (indexer, gateway).","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/GatewayErrorCode","description":"The error code."},"message":{"type":"string","description":"Human-readable error message."}}},"UpdateAuthenticatorRequest":{"type":"object","description":"The request to update an authenticator.\n\nNumeric string fields in this request accept decimal or `0x`/`0X`-prefixed hex.","required":["leaf_index","old_authenticator_address","new_authenticator_address","old_offchain_signer_commitment","new_offchain_signer_commitment","signature","nonce","pubkey_id","new_authenticator_pubkey"],"properties":{"leaf_index":{"type":"string","format":"hex","description":"The account index."},"new_authenticator_address":{"type":"string","format":"hex","description":"The new authenticator address."},"new_authenticator_pubkey":{"type":"string","format":"hex","description":"The new authenticator pubkey."},"new_offchain_signer_commitment":{"type":"string","format":"hex","description":"The new offchain signer commitment."},"nonce":{"type":"string","format":"hex","description":"The nonce."},"old_authenticator_address":{"type":"string","format":"hex","description":"The old authenticator address."},"old_offchain_signer_commitment":{"type":"string","format":"hex","description":"The old offchain signer commitment."},"pubkey_id":{"type":"string","format":"hex","description":"The pubkey id."},"signature":{"type":"string","format":"hex","description":"The signature."}}},"UpdateRecoveryAgentRequest":{"type":"object","description":"The request to update a recovery agent.\n\nNumeric string fields in this request accept decimal or `0x`/`0X`-prefixed hex.","required":["leaf_index","new_recovery_agent","signature","nonce"],"properties":{"leaf_index":{"type":"string","format":"hex","description":"The account index."},"new_recovery_agent":{"type":"string","format":"hex","description":"The new recovery agent address."},"nonce":{"type":"string","format":"hex","description":"The nonce."},"signature":{"type":"string","format":"hex","description":"The signature."}}}}},"tags":[{"name":"Gateway","description":"TODO"}]}