[{"data":1,"prerenderedAt":157},["ShallowReactive",2],{"doc:\u002Freference\u002Fmanagement\u002Fhosted-domains":3},{"page":4,"toc":150,"updated":156},{"path":5,"title":6,"seoTitle":7,"description":8,"blocks":9,"examples":130},"\u002Freference\u002Fmanagement\u002Fhosted-domains","Hosted subdomains","Management API: Hosted Subdomains","List, add, check and remove the hosted subdomains that serve the browser SDK for a site that can run no proxy. Admin keys only.",[10,13,22,27,32,71,74,76,83,85,87,90,92,94,97,100,102,105],{"type":11,"text":12},"p","A [hosted subdomain](\u002Fdocs\u002Fhosted-subdomain) is a subdomain of your site, pointed at Fingerly with a `CNAME`, that serves the browser SDK when you can run no proxy. It needs no proxy key. Only **admin** management keys can manage them; a developer key answers `403`.",{"type":14,"title":15,"fields":16},"fields","Path parameter",[17],{"name":18,"type":19,"text":20,"required":21},"organization_id","string","Your organization, from [Describe the key](\u002Freference\u002Fmanagement\u002Foverview#describe-the-key). A path naming any other organization answers `404`.",true,{"type":23,"level":24,"text":25,"id":26},"heading",2,"List hosted subdomains","list-hosted-subdomains",{"type":28,"method":29,"path":30,"auth":31},"endpoint","GET","\u002Fapi\u002Fv1\u002Fmanagement\u002Forganizations\u002F{organization_id}\u002Fhosted-domains","management",{"type":14,"title":33,"fields":34},"Response",[35,39,42],{"name":36,"type":37,"text":38},"available","boolean","Whether hosted subdomains can be added on this deployment. Existing ones can always be listed and removed.",{"name":40,"type":19,"text":41},"target","What each subdomain's `CNAME` points at. Omitted when `available` is `false`.",{"name":43,"type":44,"text":45,"children":46},"domains","HostedDomain[]","Every hosted subdomain.",[47,50,53,56,59,62,65,68],{"name":48,"type":19,"text":49},"id","The hosted subdomain's ID.",{"name":51,"type":19,"text":52},"hostname","The subdomain, such as `k7.shop.example`.",{"name":54,"type":19,"text":55},"path","Where the browser SDK posts on it, such as `\u002Fq3v8wz1p`.",{"name":57,"type":19,"text":58},"status","`pending` while the record does not resolve or the certificate is being issued, `active` once it is served, or `failed`.",{"name":60,"type":19,"text":61},"problem","Why the certificate is not issued yet, or why it failed. Omitted when there is nothing to report.",{"name":63,"type":19,"text":64},"checked_at","When its DNS and certificate were last checked.",{"name":66,"type":19,"text":67},"activated_at","When it became `active`. Omitted until then.",{"name":69,"type":19,"text":70},"created_at","When it was added.",{"type":23,"level":24,"text":72,"id":73},"Add a hosted subdomain","add-a-hosted-subdomain",{"type":28,"method":75,"path":30,"auth":31},"POST",{"type":14,"title":77,"fields":78},"Body",[79,81],{"name":51,"type":19,"text":80,"required":21},"A subdomain of your site, such as `k7.shop.example`, never the domain itself. A label a content blocker would match, such as `fp`, `metrics` or `tracking`, is refused.",{"name":54,"type":19,"text":82},"Where the browser SDK will post on it. Omit it for a random one, which is what we recommend. It follows the rules of a [proxy path](\u002Freference\u002Fmanagement\u002Fproxy-keys#paths).",{"type":11,"text":84},"Answers `201` with the hosted subdomain, `pending` until its `CNAME` to `target` resolves and its certificate is issued. Create the record, then point the browser SDK's `endpoints` at `https:\u002F\u002F\u003Chostname>\u003Cpath>`.",{"type":11,"text":86},"Pending subdomains are checked every 30 seconds, so there is no need to poll. Read the list, or check one at once, to follow it.",{"type":23,"level":24,"text":88,"id":89},"Check a hosted subdomain now","check-a-hosted-subdomain-now",{"type":28,"method":75,"path":91,"auth":31},"\u002Fapi\u002Fv1\u002Fmanagement\u002Forganizations\u002F{organization_id}\u002Fhosted-domains\u002F{hosted_domain_id}\u002Fcheck",{"type":11,"text":93},"Checks the subdomain's DNS and certificate at once, rather than at the next scheduled check, and answers with the hosted subdomain as it is now. This is **Check now** in the dashboard.",{"type":23,"level":24,"text":95,"id":96},"Remove a hosted subdomain","remove-a-hosted-subdomain",{"type":28,"method":98,"path":99,"auth":31},"DELETE","\u002Fapi\u002Fv1\u002Fmanagement\u002Forganizations\u002F{organization_id}\u002Fhosted-domains\u002F{hosted_domain_id}",{"type":11,"text":101},"Stops serving the subdomain at once, drops its certificate, and answers `204`. Delete the `CNAME` at your DNS host afterwards. There is no undo: adding the name again starts over with a new certificate.",{"type":23,"level":24,"text":103,"id":104},"Errors","errors",{"type":106,"columns":107,"rows":111},"table",[108,109,110],"Status","Code","When",[112,116,120,123,127],[113,114,115],"`404`","`hosted_domain_not_found`","No such hosted subdomain in your organization.",[117,118,119],"`409`","`hosted_domains_unavailable`","Hosted subdomains cannot be added on this deployment. `available` says so in advance.",[117,121,122],"`hosted_domain_taken`","The name is already a hosted subdomain, of your organization or another.",[124,125,126],"`422`","`hosted_domain_rejected`","The name is not usable: not a subdomain, not a valid hostname, one of Fingerly's own, or a label content blockers match. `error.message` says which.",[124,128,129],"`proxy_path_rejected`","The `path` is not valid, or contains a word content blockers match. `error.message` names it.",{"request":131,"response":139},[132,136],{"label":133,"lang":134,"code":135},"Add","bash","curl -X POST \"https:\u002F\u002Fapi.fingerly.io\u002Fapi\u002Fv1\u002Fmanagement\u002Forganizations\u002F01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37\u002Fhosted-domains\" \\\n  -H \"x-api-key: $FINGERLY_MANAGEMENT_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"hostname\": \"k7.shop.example\"\n  }'",{"label":137,"lang":134,"code":138},"Check now","curl -X POST \"https:\u002F\u002Fapi.fingerly.io\u002Fapi\u002Fv1\u002Fmanagement\u002Forganizations\u002F01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37\u002Fhosted-domains\u002F01a0a863-7f40-7c12-a3e5-8b9c0d1e2f3a\u002Fcheck\" \\\n  -H \"x-api-key: $FINGERLY_MANAGEMENT_KEY\"",[140,144,147],{"label":141,"lang":142,"code":143},"201","json","{\n  \"id\": \"01a0a863-7f40-7c12-a3e5-8b9c0d1e2f3a\",\n  \"hostname\": \"k7.shop.example\",\n  \"path\": \"\u002Fq3v8wz1p\",\n  \"status\": \"pending\",\n  \"checked_at\": \"2026-09-16T09:24:40Z\",\n  \"created_at\": \"2026-09-16T09:24:40Z\"\n}",{"label":145,"lang":142,"code":146},"422","{\n  \"error\": {\n    \"code\": \"hosted_domain_rejected\",\n    \"message\": \"content blockers match on \\\"metrics\\\"\",\n    \"status\": 422\n  },\n  \"request_id\": \"01a0a84c-0f11-7a3e-9c2d-4b5e6f708192\"\n}",{"label":148,"lang":142,"code":149},"409","{\n  \"error\": {\n    \"code\": \"hosted_domain_taken\",\n    \"message\": \"that hostname is already in use\",\n    \"status\": 409\n  },\n  \"request_id\": \"01a0a84c-0f11-7a3e-9c2d-4b5e6f708192\"\n}",[151,152,153,154,155],{"id":26,"text":25,"level":24},{"id":73,"text":72,"level":24},{"id":89,"text":88,"level":24},{"id":96,"text":95,"level":24},{"id":104,"text":103,"level":24},"2026-09-25T18:31:31.000Z",1793630453365]