Read this first if you are an AI agent that uses the Plum Guide API.
Read this page first if you are an AI agent that writes or runs code against the Plum Guide API. It lists the rules that agents most often get wrong. The other pages give the details.
Find the docs
https://docs.api.plumguide.com/llms.txtlists every page.- Add
.mdto any page address to get the page as Markdown.
Rules
- Test on staging first. Staging is
https://api.stg.plumguide.io. Production ishttps://api.plumguide.com. - The token already starts with
Bearer.POST /authenticatereturnstokenwith the prefix. Send it as it is in theAuthorizationheader. Do not addBeareragain. - Get a new token when it expires. The reply gives
expiresInin seconds. - To act for a host with a partner credential, send
X-Plum-Host-Idwith the host's id on each request. Get the ids fromGET /v2/partner/hosts. - A
403withX-Plum-Host-Idmeans the host has not approved you, or removed the approval. Do not retry it. CheckGET /v2/partner/hosts. - A
503means we could not check something. Nothing was changed. Try again later. - Do not retry a
400. Read the problem details in the body and fix the request. - Test bookings (
POST /testdata/booking) work on staging only. A400means the request is invalid, the listing has no availability for those dates, or the stay is shorter than the minimum.
Webhooks
- Answer with a
2xxwithin 30 seconds. Any other answer makes us send the event again. - Check
X-Signatureover the raw body before you parse it. - Store each
EventId. Drop an event you already processed. - Events can arrive out of order. For partner events, ignore an event older than the last one for that
HostId. - Staging sends webhooks only to domains we added. Ask us to add yours.
