{
    "name": "reseller.co.tz Reseller API Instructions",
    "version": "1.0",
    "generated_at": "2026-05-31T17:37:52+00:00",
    "purpose": "Use this file with AI coding assistants to generate safe server-side integrations for reseller.co.tz domain and DNS workflows.",
    "documentation_url": "https://reseller.co.tz/api-docs",
    "base_url": "https://reseller.co.tz/api/v1",
    "legacy_base_url": "https://reseller.co.tz/api",
    "important_ai_instructions": [
        "Build integrations on a backend server only. Never call this API directly from browser JavaScript or a public mobile app bundle.",
        "Never hard-code API keys. Read X-API-KEY from environment variables or a secret manager.",
        "Send JSON request bodies with Accept: application/json and Content-Type: application/json.",
        "Treat billable endpoints as non-idempotent unless your application adds its own idempotency key and retry protection.",
        "Display general failure messages to end users. Keep raw logs and troubleshooting details server-side.",
        "Do not expose internal registry service names, infrastructure names, credentials, or configuration details in customer-facing output."
    ],
    "authentication": {
        "required": true,
        "headers": {
            "X-API-KEY": "Your reseller API key from the reseller portal API Access page.",
            "Accept": "application/json",
            "Content-Type": "application/json for requests with a body."
        },
        "ip_whitelist": "The calling backend server IP must be whitelisted in the reseller portal. If no IP is whitelisted, API requests are blocked."
    },
    "common_response_shape": {
        "success": "boolean",
        "message": "string",
        "data": "object|null",
        "errors": "object|null, usually present on validation failures"
    },
    "common_status_codes": {
        "200": "Request completed successfully.",
        "201": "Resource created or billable action completed successfully.",
        "401": "Missing or invalid API key.",
        "403": "API key is valid but caller IP is not whitelisted or account is not allowed.",
        "404": "Domain or record was not found for the authenticated reseller account.",
        "422": "Validation failed, balance is insufficient, action is unsupported for this domain extension, or the registry operation could not be completed.",
        "429": "Too many requests.",
        "500": "Unexpected server error."
    },
    "schemas": {
        "contact": {
            "name": "required string max:120",
            "organization": "required string max:120",
            "address1": "required string max:255",
            "city": "required string max:120",
            "state": "required string max:120",
            "postcode": "required string max:30",
            "country": "required ISO 3166-1 alpha-2 country code, for example TZ",
            "phone": "required string max:40, include country code when possible",
            "email": "required valid email max:255"
        },
        "dns_record": {
            "type": "required one of A, AAAA, CNAME, MX, TXT, SRV, CAA, NS",
            "name": "required string max:253. Use @ for root, * for wildcard, or a label like www or _sip._tcp",
            "value": "required string max:1000. A requires IPv4, AAAA requires IPv6, CNAME/MX/SRV/NS require hostname",
            "ttl": "optional integer 60-86400, default 14400",
            "priority": "optional integer 0-65535, commonly used for MX and SRV",
            "weight": "optional integer 0-65535, commonly used for SRV",
            "port": "optional integer 1-65535, commonly used for SRV",
            "flag": "optional integer 0-255, commonly used for CAA",
            "tag": "optional one of issue, issuewild, iodef, commonly used for CAA"
        }
    },
    "endpoints": [
        {
            "operation_id": "listDomains",
            "method": "GET",
            "path": "/domains",
            "summary": "List domains owned by the authenticated reseller.",
            "query": {
                "q": "optional string search term",
                "status": "optional one of active, expired, pending, pending_transfer",
                "per_page": "optional integer 1-100, default 25",
                "page": "optional integer pagination page"
            },
            "billable": false
        },
        {
            "operation_id": "getDomain",
            "method": "GET",
            "path": "/domains/{domain}",
            "summary": "Get one owned domain by portal ID or full domain name.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "checkDomainAvailability",
            "method": "POST",
            "path": "/domains/check",
            "summary": "Check domain availability and return active catalog pricing when available.",
            "body": {
                "domain_name": "required valid full domain name, max 253 characters"
            },
            "billable": false
        },
        {
            "operation_id": "registerDomain",
            "method": "POST",
            "path": "/domains/register",
            "summary": "Register a domain, create local ownership, and deduct reseller balance after registry success.",
            "body": {
                "domain_name": "required valid full domain name, unique in portal",
                "period": "required integer 1-10 years",
                "nameservers": "required array of 2-10 valid hostnames",
                "provision_dns": "optional boolean, true to enable DNS management after successful registration when available",
                "registrant": "required contact object, see schemas.contact",
                "admin": "required contact object, see schemas.contact"
            },
            "billable": true,
            "success_status": 201
        },
        {
            "operation_id": "registerCancelledDomain",
            "method": "POST",
            "path": "/domains/{domain}/register",
            "summary": "Register an owned cancelled domain again, reusing the existing portal domain record.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name with cancelled status"
            },
            "body": {
                "period": "required integer 1-10 years",
                "nameservers": "required array of 2-10 valid hostnames",
                "provision_dns": "optional boolean, true to enable DNS management after successful registration when available",
                "registrant": "required contact object, see schemas.contact",
                "admin": "required contact object, see schemas.contact"
            },
            "billable": true,
            "success_status": 201
        },
        {
            "operation_id": "renewDomain",
            "method": "POST",
            "path": "/domains/{domain}/renew",
            "summary": "Renew an owned domain and deduct reseller balance after registry success.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "body": {
                "period": "required integer 1-10 years"
            },
            "billable": true
        },
        {
            "operation_id": "transferDomain",
            "method": "POST",
            "path": "/domains/{domain}/transfer",
            "summary": "Submit a domain transfer and charge configured transfer price after registry success.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name to transfer"
            },
            "body": {
                "auth_code": "required string min:6 max:128",
                "registrant": "optional contact object for providers that need account contact matching",
                "admin": "optional contact object for providers that need account contact matching"
            },
            "billable": true
        },
        {
            "operation_id": "syncDomain",
            "method": "POST",
            "path": "/domains/{domain}/sync",
            "summary": "Refresh local domain status, expiry, lock, privacy, and safe registry metadata.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "getNameservers",
            "method": "GET",
            "path": "/domains/{domain}/nameservers",
            "summary": "Fetch current nameservers for an owned domain.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "updateNameservers",
            "method": "POST",
            "path": "/domains/{domain}/nameservers",
            "summary": "Update nameservers for an owned domain.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "body": {
                "nameservers": "required array of 2-10 valid hostnames",
                "provision_dns": "optional boolean"
            },
            "billable": false
        },
        {
            "operation_id": "getChildNameservers",
            "method": "GET",
            "path": "/domains/{domain}/child-nameservers",
            "summary": "Fetch saved child nameservers and glue records for supported domain extensions.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "query": {
                "child_nsset_id": "optional saved child nameserver set ID"
            },
            "billable": false
        },
        {
            "operation_id": "updateChildNameservers",
            "method": "POST",
            "path": "/domains/{domain}/child-nameservers",
            "summary": "Save child nameservers with glue IP addresses and optionally apply them as active nameservers.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "body": {
                "child_nameserver_action": "optional save_child_nameservers or use_child_nameservers",
                "child_nameservers": "required array of 2-5 objects with label and addresses",
                "child_nameservers.*.label": "required label like ns1 or full hostname inside the same domain",
                "child_nameservers.*.addresses": "required comma or space separated IPv4/IPv6 glue addresses"
            },
            "billable": false
        },
        {
            "operation_id": "getWhois",
            "method": "GET",
            "path": "/domains/{domain}/whois",
            "summary": "Fetch current Whois contact details for an owned domain.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "updateWhois",
            "method": "POST",
            "path": "/domains/{domain}/whois",
            "summary": "Update registrant and admin Whois contact details.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "body": {
                "registrant": "required contact object, see schemas.contact",
                "admin": "required contact object, see schemas.contact"
            },
            "billable": false
        },
        {
            "operation_id": "requestEppCode",
            "method": "POST",
            "path": "/domains/{domain}/epp-code",
            "summary": "Request the current EPP/auth code for an owned domain when supported.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "setEppCode",
            "method": "PUT",
            "path": "/domains/{domain}/epp-code",
            "summary": "Set a new EPP/auth code when supported.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "body": {
                "epp_code": "required string min:8 max:128"
            },
            "billable": false
        },
        {
            "operation_id": "getDomainLock",
            "method": "GET",
            "path": "/domains/{domain}/lock",
            "summary": "Fetch domain lock status when supported for this domain extension.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "setDomainLock",
            "method": "PUT",
            "path": "/domains/{domain}/lock",
            "summary": "Enable or disable domain lock when supported for this domain extension.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "body": {
                "locked": "required boolean"
            },
            "billable": false
        },
        {
            "operation_id": "getWhoisPrivacy",
            "method": "GET",
            "path": "/domains/{domain}/privacy",
            "summary": "Fetch Whois privacy status when supported for this domain extension.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "setWhoisPrivacy",
            "method": "PUT",
            "path": "/domains/{domain}/privacy",
            "summary": "Enable or disable Whois privacy when supported for this domain extension.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "body": {
                "enabled": "required boolean"
            },
            "billable": false
        },
        {
            "operation_id": "getDnsRecords",
            "method": "GET",
            "path": "/domains/{domain}/dns",
            "summary": "Fetch DNS management status and editable records for an owned domain.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "provisionDns",
            "method": "POST",
            "path": "/domains/{domain}/dns/provision",
            "summary": "Enable DNS management for an owned domain when available.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false,
            "success_status": 201
        },
        {
            "operation_id": "cancelDns",
            "method": "DELETE",
            "path": "/domains/{domain}/dns",
            "summary": "Cancel DNS management for an owned domain.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "billable": false
        },
        {
            "operation_id": "createDnsRecord",
            "method": "POST",
            "path": "/domains/{domain}/dns/records",
            "summary": "Create a DNS record. DNS management must be active.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name"
            },
            "body": "required DNS record object, see schemas.dns_record",
            "billable": false,
            "success_status": 201
        },
        {
            "operation_id": "updateDnsRecord",
            "method": "PUT",
            "path": "/domains/{domain}/dns/records/{record}",
            "summary": "Update a DNS record by record line or record ID. DNS management must be active.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name",
                "record": "required record line or record ID returned by getDnsRecords"
            },
            "body": "required DNS record object, see schemas.dns_record",
            "billable": false
        },
        {
            "operation_id": "deleteDnsRecord",
            "method": "DELETE",
            "path": "/domains/{domain}/dns/records/{record}",
            "summary": "Delete a DNS record by record line or record ID. DNS management must be active.",
            "path_parameters": {
                "domain": "required portal domain ID or full domain name",
                "record": "required record line or record ID returned by getDnsRecords"
            },
            "billable": false
        }
    ],
    "legacy_api": {
        "use_for_new_integrations": false,
        "endpoint": "https://reseller.co.tz/api/index.php",
        "method": "POST",
        "note": "Only use the legacy action-based API for older integrations. New integrations should use /api/v1.",
        "actions": [
            "checkDomain",
            "getDomainInfo",
            "registerDomain",
            "getNameservers",
            "updateNameservers",
            "getContactDetails",
            "getWhois",
            "updateContactDetails",
            "updateWhois",
            "renewDomain",
            "getEPPCode",
            "transferDomain",
            "getBalance"
        ]
    },
    "minimal_examples": {
        "check_domain_curl": "curl -X POST \"https://reseller.co.tz/api/v1/domains/check\" -H \"X-API-KEY: $RESELLER_API_KEY\" -H \"Accept: application/json\" -H \"Content-Type: application/json\" -d \"{\\\"domain_name\\\":\\\"example.co.tz\\\"}\"",
        "recommended_env_names": {
            "RESELLER_API_BASE_URL": "https://reseller.co.tz/api/v1",
            "RESELLER_API_KEY": "store securely outside source code"
        }
    }
}