{
    "components": {
        "schemas": {
            "taldir.AliasType": {
                "properties": {
                    "challenge_fee": {
                        "description": "per challenge fee",
                        "type": "string"
                    },
                    "name": {
                        "description": "Name of the alias type, e.g. \"email\" or \"sms\".",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "taldir.Entry": {
                "properties": {
                    "target_uri": {
                        "description": "Target URI to associate with this alias",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "taldir.ErrorDetail": {
                "properties": {
                    "code": {
                        "description": "Numeric error code unique to the condition.\nThe other arguments are specific to the error value reported here.",
                        "type": "integer"
                    },
                    "currency": {
                        "description": "Name of the currency than was problematic (if applicable).",
                        "type": "string"
                    },
                    "detail": {
                        "description": "Optional detail about the specific input value that failed. May change without notice!",
                        "type": "string"
                    },
                    "hint": {
                        "description": "Human-readable description of the error, i.e. \"missing parameter\", \"commitment violation\", ...\nShould give a human-readable hint about the error's nature. Optional, may change without notice!",
                        "type": "string"
                    },
                    "index": {
                        "description": "Index of the argument that was bogus (if applicable).",
                        "type": "string"
                    },
                    "object": {
                        "description": "Name of the object that was bogus (if applicable).",
                        "type": "string"
                    },
                    "offset": {
                        "description": "Offset of the argument that was bogus (if applicable).",
                        "type": "string"
                    },
                    "parameter": {
                        "description": "Name of the parameter that was bogus (if applicable).",
                        "type": "string"
                    },
                    "path": {
                        "description": "Path to the argument that was bogus (if applicable).",
                        "type": "string"
                    },
                    "type_actual": {
                        "description": "Type that was provided instead (if applicable).",
                        "type": "string"
                    },
                    "type_expected": {
                        "description": "Expected type (if applicable).",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "taldir.RateLimitedResponse": {
                "properties": {
                    "code": {
                        "description": "Taler error code, TALER_EC_TALDIR_REGISTER_RATE_LIMITED.",
                        "type": "integer"
                    },
                    "hint": {
                        "description": "The human readable error message.",
                        "type": "string"
                    },
                    "request_frequency": {
                        "description": "At what frequency are new registrations allowed. FIXME: In what? Currently: In microseconds",
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "taldir.RegisterMessage": {
                "properties": {
                    "alias": {
                        "description": "Alias, in type-specific format",
                        "type": "string"
                    },
                    "duration": {
                        "description": "For how long should the registration last",
                        "type": "integer"
                    },
                    "target_uri": {
                        "description": "Target URI to associate with this alias",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "taldir.ValidationConfirmation": {
                "properties": {
                    "solution": {
                        "description": "The solution is the SHA-512 hash of the challenge value\nchosen by TalDir (encoded as string just as given in the URL, but\nexcluding the 0-termination) concatenated with the binary 32-byte\nvalue representing the wallet's EdDSA public key.\nThe hash is provided as string in Crockford base32 encoding.",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "taldir.VersionResponse": {
                "properties": {
                    "alias_type": {
                        "description": "Supported alias types",
                        "items": {
                            "$ref": "#/components/schemas/taldir.AliasType"
                        },
                        "type": "array",
                        "uniqueItems": false
                    },
                    "monthly_fee": {
                        "description": "fee for one month of registration",
                        "type": "string"
                    },
                    "name": {
                        "description": "Name of the protocol.",
                        "type": "string"
                    },
                    "version": {
                        "description": "libtool-style representation of the Merchant protocol version, see\nhttps://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning\nThe format is \"current:revision:age\".",
                        "type": "string"
                    }
                },
                "type": "object"
            }
        }
    },
    "info": {
        "contact": {
            "url": "https://taler.net"
        },
        "description": "The Taler Directory (TalDir) maps alias hashes to wallet URIs. Clients register an alias by completing an out-of-band challenge, then look it up later using the hashed alias.",
        "license": {
            "name": "AGPL-3.0-or-later",
            "url": "https://www.gnu.org/licenses/agpl-3.0.html"
        },
        "title": "Taler Directory API",
        "version": ""
    },
    "externalDocs": {
        "description": "",
        "url": ""
    },
    "paths": {
        "/config": {
            "get": {
                "description": "Returns service metadata including the supported alias types and monthly fee.",
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/taldir.VersionResponse"
                                }
                            }
                        },
                        "description": "OK"
                    }
                },
                "summary": "Get service configuration",
                "tags": [
                    "config"
                ]
            }
        },
        "/register/{alias_type}": {
            "post": {
                "description": "Starts the registration process for an alias. Sends an out-of-band challenge\nvia the specified validator (e.g. email or SMS). If the entry already exists\nwith no changes, returns the remaining validity instead.",
                "parameters": [
                    {
                        "description": "Alias type (e.g. \\",
                        "in": "path",
                        "name": "alias_type",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "type": "object"
                                    },
                                    {
                                        "$ref": "#/components/schemas/taldir.RegisterMessage",
                                        "summary": "body",
                                        "description": "Registration request"
                                    }
                                ]
                            }
                        }
                    },
                    "description": "Registration request",
                    "required": true
                },
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "valid_for": {
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "description": "Existing entry unchanged; returns remaining validity in microseconds"
                    },
                    "202": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        },
                        "description": "Challenge sent"
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/taldir.ErrorDetail"
                                }
                            }
                        },
                        "description": "Invalid request body or target URI"
                    },
                    "402": {
                        "description": "Payment required"
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/taldir.ErrorDetail"
                                }
                            }
                        },
                        "description": "Alias type not supported"
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/taldir.RateLimitedResponse"
                                }
                            }
                        },
                        "description": "Registration rate limit reached"
                    },
                    "500": {
                        "description": "Internal Server Error"
                    }
                },
                "summary": "Initiate alias registration",
                "tags": [
                    "registration"
                ]
            }
        },
        "/{h_alias}": {
            "get": {
                "description": "Returns the target URI associated with the given hashed alias.",
                "parameters": [
                    {
                        "description": "Crockford base32-encoded SHA-512 hash of the alias",
                        "in": "path",
                        "name": "h_alias",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/taldir.Entry"
                                }
                            }
                        },
                        "description": "OK"
                    },
                    "404": {
                        "description": "Not Found"
                    }
                },
                "summary": "Look up an alias entry",
                "tags": [
                    "entries"
                ]
            },
            "post": {
                "description": "Submits the solution to the out-of-band challenge to confirm the registration.",
                "parameters": [
                    {
                        "description": "Crockford base32-encoded SHA-512 hash of the alias",
                        "in": "path",
                        "name": "h_alias",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "type": "object"
                                    },
                                    {
                                        "$ref": "#/components/schemas/taldir.ValidationConfirmation",
                                        "summary": "body",
                                        "description": "Challenge solution"
                                    }
                                ]
                            }
                        }
                    },
                    "description": "Challenge solution",
                    "required": true
                },
                "responses": {
                    "204": {
                        "description": "Registration confirmed"
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/taldir.ErrorDetail"
                                }
                            }
                        },
                        "description": "Invalid JSON"
                    },
                    "403": {
                        "description": "Wrong solution"
                    },
                    "404": {
                        "description": "Validation not found"
                    },
                    "429": {
                        "description": "Too many solution attempts"
                    },
                    "500": {
                        "description": "Internal Server Error"
                    }
                },
                "summary": "Complete alias registration",
                "tags": [
                    "registration"
                ]
            }
        }
    },
    "openapi": "3.1.0",
    "servers": [
        {
            "url": "/"
        }
    ]
}