01Connect Claude (MCP)
Connect Claude to your Husly account, then ask it in plain words to build or change your site. Claude does it with the Husly builder's own tools: it makes the page, writes the texts, adds the pictures and puts the page in the menu.
The Claude connection is part of every paid plan, not the Free plan. You need no API key: you log in with your own Husly account.
Connect in claude.ai
- 1Add the connectorIn claude.ai, open the settings and find the connectors. Add a custom connector with the name Husly and the address
https://api.husly.app/mcp. - 2Log inConnect the new connector. A Husly page opens: log in with your Husly account.
- 3AllowHusly shows what Claude may do. Press Allow. Done: tell Claude what to change on your site.
The Claude desktop app uses the same connector list: once you add Husly in claude.ai, it is there too. In Claude Code, add Husly with one command, then log in with /mcp.
Claude Code
claude mcp add --transport http husly https://api.husly.app/mcp
# Then, in Claude Code: type /mcp, pick husly and log in to Husly in the browser.What to ask
"Make a page about our prices with three packages and add it to the menu."
"Make the homepage headline and intro friendlier, but keep the facts."
"Put fitting photos on the cards of the services page."
"Improve the SEO titles and descriptions of every page."
"Undo the changes you made today."
Claude is told not to make up facts the site does not have (prices, names, a phone number) and to ask you before it publishes a page.
What Claude can do
| Tool | What it does | On the site |
|---|---|---|
list_sites | Your sites, their languages and whether Claude may change them. | reads |
create_page | Makes a new, empty page, a draft by default. | changes |
list_pages | The site's pages: which are drafts and which are live. | reads |
read_page_layout | Reads a page's blocks, texts and picture spots. | reads |
list_sections | The ready-made sections a page can get. | reads |
read_widget | Reads one block's settings. | reads |
edit_theme | Changes the site's colours, corners and fonts. | changes |
rewrite_copy | Rewrites texts on a page. | changes |
add_section | Adds a ready-made section to a page. | changes |
restructure | Moves the blocks that are there: into columns, into a section or to another place. | changes |
edit_widget | Changes a block's settings: layout, colours, sizes. | changes |
edit_widget_rows | Adds, removes or reorders a block's rows: slides, cards, plans, questions. | changes |
search_stock_photo | Finds a real photo in a stock library and puts it on the page. | changes |
translate | Translates the site into its other languages. Uses AI credit. | changes |
fix_seo | Writes better SEO titles and descriptions for the pages. Uses AI credit. | changes |
fix_alt_text | Fills in missing alt texts for pictures. Uses AI credit. | changes |
set_brand_voice | Saves the site's brand voice: tone, call to action and emphasis. | changes |
set_page_status | Publishes a page, or turns it back into a draft. | changes |
read_menus | Reads the site's menus. | reads |
set_menu | Replaces the items of one menu. | changes |
list_restore_points | The restore points taken before Claude's changes. | reads |
restore_point | Takes the whole site back to a restore point. | changes |
figma_import_frame | Imports a Figma frame as draft pages. | changes |
figma_import_status | How a Figma import went and which draft pages it made. | reads |
figma_resync | Reads the Figma file again and writes only the changes you pick. | changes |
Safety and limits
| Rule | What happens |
|---|---|
| Your role | Claude can do only what you can do in the builder: you need the right to manage pages on the site. A tool your role or the site's plan does not allow answers with a refusal and the reason. |
| Restore points | Husly saves a restore point of the site before Claude's first change, and a new one at the first change after 30 minutes. If you do not like the result, ask Claude to take the site back to a restore point. The brand voice is a setting and stays outside it. |
| AI credit | Translation and the SEO tools use the site's monthly AI credit and keep the same plan and permission limits as in the builder. When the credit runs out, Claude tells you. Claude writes the texts itself, which uses no Husly credit. Pictures come from a stock library; AI pictures are made in the Husly builder, not through the Claude connection. |
| Audit log | Every change goes into the audit log: who, through which app, with which tool and when. |
| Disconnect | Open account.husly.app, then My account -> Security -> Connected apps. Once you disconnect, Claude can no longer reach your sites. |
The Claude connection is not the account API (key hsly_live_, Agency plan) or the Rentals partner MCP server further down (key hsly_partner_). Claude works as you, and only on the sites you may change yourself.
For developers
Husly is both the MCP server and the OAuth 2.1 authorization server, on the same host. An MCP client finds everything by itself: without a token, POST https://api.husly.app/mcp answers 401, and its WWW-Authenticate header points at the protected resource metadata. From there the client registers itself (dynamic client registration) and logs the person in with PKCE (S256 only). Clients are public: there is no client secret. A redirect address must be https, or http on a loopback address, and it must match exactly later. The one scope that gives a right is sites.build; offline_access only asks for a refresh token, which every login gets anyway.
The answer without a token
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.husly.app/.well-known/oauth-protected-resource/mcp", scope="sites.build"Addresses
| What | Address |
|---|---|
| MCP server | POST https://api.husly.app/mcp |
| Protected resource metadata (RFC 9728) | GET https://api.husly.app/.well-known/oauth-protected-resource/mcp |
| Authorization server metadata (RFC 8414) | GET https://api.husly.app/.well-known/oauth-authorization-server |
| Client registration (RFC 7591) | POST https://api.husly.app/oauth/register |
| Login and consent | GET https://api.husly.app/oauth/authorize |
| Tokens | POST https://api.husly.app/oauth/token |
| Token revocation | POST https://api.husly.app/oauth/revoke |
An authorization code lives 5 minutes, an access token 1 hour and a refresh token 60 days. A refresh swaps both tokens and starts both clocks again; an old refresh token works once.
The MCP server speaks MCP 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. Every POST gets one JSON answer (no stream); GET and DELETE get 405.
02Connect ChatGPT or Codex (MCP)
ChatGPT and Codex connect to Husly the same way Claude does: the same address https://api.husly.app/mcp, the same Husly login and the same Allow button. They get the same tools and the same limits: your role, restore points, AI credit and the audit log. Those are described under Connect Claude.
The connection is part of every paid Husly plan. You need no API key.
Connect ChatGPT
- 1Add the serverOn chatgpt.com, open Plugins, press + and choose Add custom MCP server. Name: Husly. Server URL:
https://api.husly.app/mcp. Authentication: OAuth. - 2CreateTick I understand and want to continue and press Create as a plugin.
- 3Log in and allowWhen ChatGPT asks, log in with your Husly account and press Allow. In a chat, pick Husly with @ and say what to change on your site.
Choose OAuth as the authentication, not "No authentication" or the mixed option. Husly answers only a person who has logged in, so without OAuth ChatGPT sees no tools.
Codex
Codex (the terminal and the IDE extension) adds Husly with one command. Codex finds the login by itself and opens it in your browser: log in with your Husly account and press Allow. The Codex IDE extension reads the same settings (~/.codex/config.toml), so you add Husly once.
Codex
codex mcp add husly --url https://api.husly.app/mcp
# Codex finds the Husly login by itself and opens it in your browser.
# To log in again later (for example after you disconnected it in My account):
codex mcp login huslyThe same in the settings
[mcp_servers.husly]
url = "https://api.husly.app/mcp"Who and where
| What | ChatGPT | Codex |
|---|---|---|
| Where | chatgpt.com on the web. Not in the phone app. | The Codex terminal (CLI) and the IDE extension. |
| ChatGPT plan | A Business, Enterprise or Edu workspace. ChatGPT Pro can use only the tools that read. | No extra plan: Codex reads MCP servers from its own settings. |
| Workspace admin | In Business, admins and owners add the server. In Enterprise and Edu, an admin gives a role the right to create plugins with MCP. A published plugin keeps a snapshot of the tools: when Husly adds tools, an admin presses Refresh. | Not needed. |
| Approvals | ChatGPT asks you before each of the 17 tools that change the site. The 8 tools that only read run without asking. | Codex's own approval settings. |
For developers
Nothing extra to set up: both find the server from its 401 answer, like Claude (see Connect Claude). ChatGPT registers itself once as a public client (dynamic client registration) and comes back to https://chatgpt.com/connector/oauth/.... Codex registers at every login and comes back to your own computer, http://127.0.0.1:<port>/callback/.... Both ask for the scopes sites.build offline_access and send the resource from the protected resource metadata.
offline_access adds no right: Husly gives every login a refresh token anyway. It is listed because ChatGPT keeps its connection past the first hour only then. MCP versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26.
03Get started
With the account API you manage your account's sites from a script, from Zapier or from your agency tooling. It is part of the Agency plan, and the account owner creates the key.
- 1Create a keyMy account -> API keys -> New key. Give it a name you will recognise later.
- 2Choose scopesTick only the modules this key needs. Ticking write includes read.
- 3Make the first callSend the key in the Authorization header. Start with
/api/v1/me: it reports what your key may do.
# Who am I? Returns the account id and the key's scopes.
curl https://api.husly.app/api/v1/me \
-H "Authorization: Bearer hsly_live_ab12cd34ef56_..."
# List the sites on this account.
curl https://api.husly.app/api/v1/sites \
-H "Authorization: Bearer hsly_live_ab12cd34ef56_..."Every endpoint answers with JSON shaped { "data": ... }. An error is { "error": "code" }.
The full key is shown exactly ONCE. We store only a hash of it, so a lost key cannot be shown again: create a new one and revoke the old.
04Authentication
Every request carries the API key. Both forms below work the same way: use whichever your tool supports. A key always starts with hsly_live_. A request with no key, a revoked key or an expired one gets a 401.
Authorization: Bearer hsly_live_ab12cd34ef56_XXXXXXXXXXXXXXXXXXXXXXXX
# or
X-Api-Key: hsly_live_ab12cd34ef56_XXXXXXXXXXXXXXXXXXXXXXXXNever put a key in browser-side code or in a public repository: it reaches the whole account. Keep it in a server-side environment variable. A leaked key can be revoked at once and replaced.
05Scopes
A key carries exactly the scopes you ticked when you created it. A missing scope answers 403 insufficient_scope. Give each key only what it truly needs: a Zapier key that reads form replies has no business deleting sites.
| Scope | Allows |
|---|---|
sites:read | List the account's sites and read one site's details |
sites:write | Create a new site (counts against the plan's site quota) |
pages:read | List pages, read a page including its block tree |
pages:write | Create, update and delete pages; publish and unpublish |
blog:read | List and read blog posts, categories and tags |
blog:write | Create, update and delete posts and terms |
media:read | List the media library |
media:write | Import an image by URL, retitle it, move it, trash it |
forms:read | List forms and their submissions |
forms:write | Mark a submission read, delete a submission |
redirects:read | List the site's URL redirects |
redirects:write | Create, update and delete redirects |
navigation:read | Read the header and footer menu trees |
navigation:write | Replace a menu's items |
analytics:read | Read daily traffic totals and dimension breakdowns |
webhooks:read | List webhooks and their delivery attempts |
webhooks:write | Create, update and delete webhooks |
06Endpoints
Every path is relative to https://api.husly.app. :siteId is the site id from the GET /api/v1/sites response. The site must belong to your account: a stranger's site id answers 404, not 403, because a key must not learn that other accounts exist.
Account
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/me | any valid key |
| GET | /api/v1/webhook-events | webhooks:read |
Sites
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites | sites:read |
| GET | /api/v1/sites/:siteId | sites:read |
| POST | /api/v1/sites | sites:write |
Pages
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites/:siteId/pages | pages:read |
| GET | /api/v1/sites/:siteId/pages/:pageId | pages:read |
| POST | /api/v1/sites/:siteId/pages | pages:write |
| PUT | /api/v1/sites/:siteId/pages/:pageId | pages:write |
| DELETE | /api/v1/sites/:siteId/pages/:pageId | pages:write |
Blog
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites/:siteId/posts | blog:read |
| GET | /api/v1/sites/:siteId/posts/:postId | blog:read |
| POST | /api/v1/sites/:siteId/posts | blog:write |
| PUT | /api/v1/sites/:siteId/posts/:postId | blog:write |
| DELETE | /api/v1/sites/:siteId/posts/:postId | blog:write |
| GET | /api/v1/sites/:siteId/terms | blog:read |
| POST | /api/v1/sites/:siteId/terms | blog:write |
| PUT | /api/v1/sites/:siteId/terms/:termId | blog:write |
| DELETE | /api/v1/sites/:siteId/terms/:termId | blog:write |
Media
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites/:siteId/media | media:read |
| POST | /api/v1/sites/:siteId/media | media:write |
| PATCH | /api/v1/sites/:siteId/media/:mediaId | media:write |
| DELETE | /api/v1/sites/:siteId/media/:mediaId | media:write |
Forms
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites/:siteId/forms | forms:read |
| GET | /api/v1/sites/:siteId/form-submissions | forms:read |
| GET | /api/v1/forms/submissions?siteId= | forms:read |
| PATCH | /api/v1/sites/:siteId/form-submissions/:id | forms:write |
| DELETE | /api/v1/sites/:siteId/form-submissions/:id | forms:write |
Redirects
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites/:siteId/redirects | redirects:read |
| POST | /api/v1/sites/:siteId/redirects | redirects:write |
| PUT | /api/v1/sites/:siteId/redirects/:id | redirects:write |
| DELETE | /api/v1/sites/:siteId/redirects/:id | redirects:write |
Menus
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites/:siteId/menus | navigation:read |
| GET | /api/v1/sites/:siteId/menus/:key | navigation:read |
| PUT | /api/v1/sites/:siteId/menus/:key | navigation:write |
Analytics
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites/:siteId/analytics | analytics:read |
| GET | /api/v1/sites/:siteId/analytics/breakdown | analytics:read |
Webhooks
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/sites/:siteId/webhooks | webhooks:read |
| GET | /api/v1/sites/:siteId/webhooks/:id/deliveries | webhooks:read |
| POST | /api/v1/sites/:siteId/webhooks | webhooks:write |
| PUT | /api/v1/sites/:siteId/webhooks/:id | webhooks:write |
| DELETE | /api/v1/sites/:siteId/webhooks/:id | webhooks:write |
An image import by URL fetches the file from a public http or https address only, and waits until the WebP variants are ready. Deleting a form submission deletes the files uploaded with it too.
07Example: publish a blog post
A post's body is a block tree: the same shape the builder saves. The simplest start is a single richtext block. Leave layoutJson out and you get an empty post you can finish in the builder.
curl -X POST https://api.husly.app/api/v1/sites/SITE_ID/posts \
-H "Authorization: Bearer hsly_live_..." \
-H "Content-Type: application/json" \
-d '{
"slug": "kevadised-pakkumised",
"title": { "et": "Kevadised pakkumised", "en": "Spring offers" },
"excerpt": { "et": "Lühike sissejuhatus.", "en": "A short intro." },
"status": "published",
"authorName": "Mari Maasikas",
"layoutJson": {
"contentWidth": "narrow",
"blocks": [
{ "id": "b1", "type": "richtext", "props": {
"content": { "et": "<p>Tere tulemast!</p>", "en": "<p>Welcome!</p>" } } }
]
}
}'08Errors
An error is always JSON shaped { "error": "code" }, sometimes with extra fields (required, limit and so on). The code is machine-readable and stable: branch on the code, never on the message.
| HTTP | error | What it means |
|---|---|---|
| 400 | invalid_input | The body failed validation; the details field lists what failed. |
| 400 | invalid_url | The import or webhook address is not a public http or https address. |
| 401 | unauthorized | No key was sent. |
| 401 | invalid_key | Unknown or revoked key. |
| 401 | key_expired | The key passed its expiry date. |
| 402 | plan_required | The plan does not include this feature; the feature field names it. |
| 402 | site_quota_exceeded | The plan's site limit is reached. |
| 402 | storage_quota_exceeded | The file would go over the storage quota. |
| 403 | api_not_entitled | The account's plan has no API access. |
| 403 | insufficient_scope | The key lacks the scope named in the required field. |
| 403 | forbidden_widget | The block tree uses a widget this account may not place. |
| 404 | site_not_found | No such site, or it belongs to another account. |
| 404 | *_not_found | No such page, post, file, submission, redirect, menu or webhook in the path (page_not_found, post_not_found and so on). |
| 409 | slug_taken | That slug already exists on this site. |
| 409 | from_path_taken | A redirect from that path already exists; the id field names it. |
| 413 | file_too_large | The imported file is over the size limit. |
| 415 | unsupported_type | The imported file is not an allowed image type. |
| 429 | rate_limited | Too many requests; retry after the Retry-After header. |
| 502 | download_failed | The import address did not answer with a file (also download_failed_<status> and empty_download). |
09Limits and versions
Requests are capped per key per minute. Going over answers 429 with a Retry-After header, and the body's limit field says which cap applied. Plan quotas (number of sites, number of pages, storage) apply through the API as well: a script cannot walk around them.
The current version is v1. We will not reshape a v1 response in a way that breaks your integration: new fields may appear, existing ones will not vanish. A breaking change would mean a new path (/api/v2/).
10Webhooks
A webhook sends your server a signed POST the moment something happens on the site, so you never have to poll the API on a timer.
Make one in the admin (Tools -> Integrations: Make, Zapier or your own address) or through the account API (POST /api/v1/sites/:siteId/webhooks). The admin needs no API key. On a plan without webhooks the API answers 402 plan_required.
Events
| Event | When | What data carries |
|---|---|---|
form.submitted | A visitor sends a form. | id, formName, fields, createdAt |
page.published | A page is published. | id, slug, title, isHomepage, publishedAt |
post.published | A blog post is published. | id, slug, title, publishedAt |
feedback.received | A feedback form gets an answer. | id, formId, rating, fields, source, createdAt |
experiment.result_clear | An A/B test reaches a clear result. | id, name, page, goal, winnerKey, variants |
experiment.completed | An A/B test ends: by hand, on its date or on a clear result. | id, name, stoppedReason, winnerKey, variants |
booking.created | A new Rentals booking is made. | id, code, listing, startsAt, endsAt, total, currency, customer |
payment.succeeded | A payment goes through. | id, provider, amount, currency, sourceType, sourceId, receiptUrl |
chat.started | A visitor starts a Live chat. | id, visitor, locale, firstMessage, createdAt |
What arrives
POST /hooks/husly HTTP/1.1
Content-Type: application/json
X-Husly-Event: form.submitted
X-Husly-Delivery: cm4x8d2k70001
X-Husly-Timestamp: 1793268214
X-Husly-Signature: sha256=5f2c9a...
{
"event": "form.submitted",
"occurredAt": "2026-10-29T09:23:34.512Z",
"siteId": "cm1q7z0b40000",
"data": {
"id": "cm4x8d1f90002",
"formName": "Contact",
"fields": { "name": "Mari Maasikas", "email": "[email protected]", "message": "Hi" },
"createdAt": "2026-10-29T09:23:34.488Z"
}
}The signature is X-Husly-Signature: sha256=<hex>: the HMAC-SHA256 of <timestamp>.<body> with the webhook's secret (whsec_). The API returns the secret only in the answer that creates the webhook; the admin can show it again or make a new one. Check the signature before you trust a request.
Check the signature (Node.js)
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
// Keep the raw body: the signature covers the exact bytes that were sent.
app.post("/hooks/husly", express.raw({ type: "application/json" }), (req, res) => {
const ts = req.get("X-Husly-Timestamp") ?? "";
const sig = req.get("X-Husly-Signature") ?? "";
const body = req.body.toString("utf8");
// Every attempt is signed again, so an old timestamp means a replay.
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
const expected = "sha256=" + createHmac("sha256", process.env.HUSLY_WEBHOOK_SECRET)
.update(`${ts}.${body}`)
.digest("hex");
const ok = sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!ok) return res.sendStatus(401);
const { event, data, test } = JSON.parse(body);
// ... your work here. Answer fast: a slow job belongs in your own queue.
res.sendStatus(204);
});Delivery rules
| Rule | What happens |
|---|---|
| Answer | Any 2xx answer within 10 seconds counts as delivered. |
| Retries | Up to 5 attempts in all: at once, then after about 5 minutes, 30 minutes, 2 hours and 6 hours. Every attempt is signed again. |
| Switch-off | After 10 deliveries in a row fail for good, the webhook switches itself off. Switch it on again in the admin, or with PUT and "active": true. |
| Address | A public http or https address only. A redirect (3xx) is not followed: the signed body goes to the address you typed and nowhere else. |
| Log | Every attempt and its answer code is in the admin and in GET .../webhooks/:id/deliveries. |
In the admin, "Send a test" sends the site's newest real record of the chosen event, or a sample of the same shape, marked "test": true. Make or Zapier learn the fields before anyone fills in a form.
11The Rentals partner API
A separate API for travel agencies, channel managers and AI agents that sell one Husly rental business's cars, bikes, boats, gear or places to stay. The site owner makes the key on the Rentals "Integrations" tab (Partner API) and gives it to the partner. A key opens that one site only: its published catalogue and the bookings the partner made. No Agency plan is needed: it comes with the Rentals add-on.
A partner key starts with hsly_partner_ and works only under /api/partner/v1/rentals. An account API key (hsly_live_) does not work here, and a partner key does not work in the account API.
Search, hold, confirm
# The site, its terms, and what this key may do.
curl https://api.husly.app/api/partner/v1/rentals/me \
-H "Authorization: Bearer hsly_partner_ab12cd34ef56_..."
# What is free from 12 to 14 June, with the lowest price.
curl "https://api.husly.app/api/partner/v1/rentals/listings?from=2027-06-12&to=2027-06-14" \
-H "Authorization: Bearer hsly_partner_ab12cd34ef56_..."
# Hold a car for 20 minutes...
curl -X POST https://api.husly.app/api/partner/v1/rentals/bookings \
-H "Authorization: Bearer hsly_partner_ab12cd34ef56_..." \
-H "Content-Type: application/json" \
-d '{
"listing": "toyota-rav4",
"from": "2027-06-12",
"to": "2027-06-14",
"guest": { "name": "Mari Maasikas", "email": "[email protected]", "phone": "+372 5555 5555" },
"termsAccepted": true,
"hold": true,
"reference": "AG-10442"
}'
# ...and book it once the traveller says yes.
curl -X POST https://api.husly.app/api/partner/v1/rentals/bookings/BOOKING_ID/confirm \
-H "Authorization: Bearer hsly_partner_ab12cd34ef56_..."Partner API endpoints
| Method | Path | Needs |
|---|---|---|
| GET | /api/partner/v1/rentals/me | any partner key |
| GET | /api/partner/v1/rentals/listings | any partner key |
| GET | /api/partner/v1/rentals/listings/:slug | any partner key |
| GET | /api/partner/v1/rentals/listings/:slug/calendar | any partner key |
| GET | /api/partner/v1/rentals/listings/:slug/quote | any partner key |
| GET | /api/partner/v1/rentals/bookings | any partner key |
| POST | /api/partner/v1/rentals/bookings | a key that may book |
| GET | /api/partner/v1/rentals/bookings/:id | any partner key |
| POST | /api/partner/v1/rentals/bookings/:id/confirm | a key that may book |
| POST | /api/partner/v1/rentals/bookings/:id/cancel | a key that may book |
| GET | /api/partner/v1/rentals/webhook | any partner key |
| PUT | /api/partner/v1/rentals/webhook | any partner key |
| DELETE | /api/partner/v1/rentals/webhook | any partner key |
| POST | /api/partner/v1/rentals/webhook/test | any partner key |
| POST | /api/partner/v1/rentals/mcp | any partner key |
| GET | /api/partner/v1/rentals/openapi.json | no key |
| GET | /api/partner/v1/rentals/docs | no key |
"hold": true keeps the dates for 20 minutes (at most 60) and writes to nobody. POST /bookings/:id/confirm books them; a hold that is not confirmed lets the dates go by itself. Sending the same "reference" again returns the same booking, not a second one. The price and the free days are the same as on the rental business's own site. A partner's booking is not paid on Husly: the partner settles the money with the renter.
The partner sets its own webhook address with PUT /api/partner/v1/rentals/webhook; the signing secret comes back the first time, or when you send "rotate": true. Events: rental.booking.created, rental.booking.confirmed, rental.booking.cancelled, for the partner's own bookings only. The signature, the answer time and the retries are the same as the site webhooks' (see Webhooks). A partner webhook that switched itself off switches on again when you set its address again.
Partner API errors
| HTTP | error | What it means |
|---|---|---|
| 401 | invalid_key | No partner key, an unknown one, or one the owner revoked (also unauthorized, key_revoked). |
| 403 | read_only_key | This key may read but not book. |
| 403 | rentals_off | The site's Rentals add-on or module is off. |
| 404 | listing_not_found | No such listing, or not a booking this key made (also booking_not_found). |
| 409 | unavailable | The dates are taken; the detail says why. |
| 409 | hold_expired | The hold ran out, or the rental has begun (also already_started). |
| 422 | invalid_guest | Guest details are missing, or the range cannot be priced (also not_bookable). |
| 429 | rate_limited | 120 requests a minute or 60 new bookings an hour per key (also too_many_bookings). |
Below is every endpoint on its own: what it does, its parameters and its answer codes. The paths are under /api/partner/v1/rentals, and the error codes are explained in the table above. The descriptions come straight from the OpenAPI 3.1 file, which also holds every field and every answer's shape: load it into Postman or generate a client from it.
GET /me
Your key, the site and its terms.
- Answer
200The profile.- Errors
401,403,429
GET /listings
The published catalogue. With from and to only the listings free on those days are kept.
- category (query)
- A category slug.
- from (query)
- First day, YYYY-MM-DD.
- to (query)
- Last day, YYYY-MM-DD.
- Answer
200The catalogue.- Errors
400,401,403,404,429
GET /listings/:slug
One listing.
- slug (path, required)
- The listing's slug.
- Answer
200The listing.- Errors
401,403,404,429
GET /listings/:slug/calendar
Free and taken days.
- slug (path, required)
- The listing's slug.
- from (query)
- First day, YYYY-MM-DD. Default today.
- days (query)
- How many days, 1 to 62. Default 31.
- Answer
200The days.- Errors
400,401,403,404,429
GET /listings/:slug/quote
Price and availability for a range.
- slug (path, required)
- The listing's slug.
- from (query, required)
YYYY-MM-DD, orYYYY-MM-DDTHH:MMfor a rental priced by the hour, in the listing's time zone.- to (query, required)
YYYY-MM-DD, orYYYY-MM-DDTHH:MMfor a rental priced by the hour, in the listing's time zone.- extras (query)
- Add-ons as
id:qty,id:qty. - Answer
200Both answers, even when one refuses.- Errors
400,401,403,404,429
GET /bookings
Your bookings.
- status (query)
- held, pending, confirmed, cancelled, expired, completed or noshow.
- reference (query)
- Your own reference.
- limit (query)
- 1 to 100. Default 50.
- offset (query)
- Default 0.
- Answer
200Newest first.- Errors
401,403,429
POST /bookings
Book, or hold the dates.
- Answer
200The samereferencealready holds dates: that booking.201Booked or held.- Errors
400,401,403,404,409,422,429
GET /bookings/:id
One of your bookings.
- id (path, required)
- The booking id.
- Answer
200The booking.- Errors
401,403,404,429
POST /bookings/:id/confirm
Confirm a hold.
- id (path, required)
- The booking id.
- Answer
200Booked:confirmed, orpendinguntil the business answers.- Errors
401,403,404,409,429
POST /bookings/:id/cancel
Cancel a booking or let a hold go.
- id (path, required)
- The booking id.
- Answer
200Cancelled (or expired, for a hold).- Errors
401,403,404,409,429
GET /webhook
Your webhook.
- Answer
200Null when none is set.- Errors
401,403,429
PUT /webhook
Set the address. The signing secret is in the answer when the webhook is new, or with rotate: true. Store it then.
- Answer
200Updated.201Created, with the secret.- Errors
400,401,403,429
DELETE /webhook
Remove it.
- Answer
200Removed.- Errors
401,403,429
POST /webhook/test
Send a `ping`.
- Answer
202Queued.- Errors
401,403,404,429
POST /mcp
The MCP server (JSON-RPC 2.0). Protocol 2026-07-28 (stateless: server/discover, tools/list, tools/call, with MCP-Protocol-Version, Mcp-Method and Mcp-Name headers) and 2025-03-26 to 2025-11-25 (initialize, ping, tools/list, tools/call). One message per request; a notification gets 202.
- Answer
200The JSON-RPC answer.202A notification: no answer.- Errors
401,403,429
GET /openapi.json
This document.
- Answer
200OpenAPI 3.1.
GET /docs
The reference for people, on husly.app.
- Answer
301Moved to https://husly.app/en/developers#partner-api.
12AI agents (MCP)
The same partner API is also an MCP server at POST /api/partner/v1/rentals/mcp, with the same key. It speaks MCP 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. Add it to your agent's settings like this:
{
"mcpServers": {
"husly-rentals": {
"type": "http",
"url": "https://api.husly.app/api/partner/v1/rentals/mcp",
"headers": {
"Authorization": "Bearer hsly_partner_ab12cd34ef56_..."
}
}
}
}Tools
| Tool | What it does |
|---|---|
rentals_site_info | The rental business, its terms and what the key may do. |
search_rentals | What is free on given dates, with the lowest price. |
get_rental | One listing's description, photos and prices. |
get_rental_calendar | One listing's free and taken days. |
quote_rental | The exact price for a chosen range. |
book_rental | Holds the dates, or books them. |
confirm_booking | Turns a hold into a booking. |
cancel_booking | Cancels one of the partner's bookings. |
get_booking | The state of one of the partner's bookings. |
list_bookings | The partner's bookings. |
A read-only key gets no booking tools. book_rental holds the dates by default and tells the agent to get the traveller's yes before confirm_booking.
13Frequently asked questions
Who can create an API key?
The account owner. A key belongs to the account rather than to a single site, and reaches every site on that account.
Can I see the key again later?
No. We store only a hash of the key, never the key itself. The list shows just the prefix (for example hsly_live_ab12cd34). If you lose a key, create a new one and revoke the old.
What happens when I revoke a key?
It stops working at once: the next request gets a 401. The row stays in the list, so the record of when and from where it was used survives.
Can a key have an expiry date?
Yes. An expired key answers 401 key_expired. It is a good idea for short-lived work, such as a one-off migration script.
Do Make or Zapier need an API key?
No. Make and Zapier get the data with a webhook: make it in the admin under Tools -> Integrations and press "Send a test" so they learn the fields. You need an API key only when you also want to write to Husly.
Can a travel agency book a rental business's items through the API?
Yes, through the Rentals partner API. The rental business gives the partner its key, and the key opens that one site only. An account API key does not do this.