For AI agents

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.txt lists every page.
  • Add .md to any page address to get the page as Markdown.

Rules

  1. Test on staging first. Staging is https://api.stg.plumguide.io. Production is https://api.plumguide.com.
  2. The token already starts with Bearer . POST /authenticate returns token with the prefix. Send it as it is in the Authorization header. Do not add Bearer again.
  3. Get a new token when it expires. The reply gives expiresIn in seconds.
  4. To act for a host with a partner credential, send X-Plum-Host-Id with the host's id on each request. Get the ids from GET /v2/partner/hosts.
  5. A 403 with X-Plum-Host-Id means the host has not approved you, or removed the approval. Do not retry it. Check GET /v2/partner/hosts.
  6. A 503 means we could not check something. Nothing was changed. Try again later.
  7. Do not retry a 400. Read the problem details in the body and fix the request.
  8. Test bookings (POST /testdata/booking) work on staging only. A 400 means the request is invalid, the listing has no availability for those dates, or the stay is shorter than the minimum.

Webhooks

  1. Answer with a 2xx within 30 seconds. Any other answer makes us send the event again.
  2. Check X-Signature over the raw body before you parse it.
  3. Store each EventId. Drop an event you already processed.
  4. Events can arrive out of order. For partner events, ignore an event older than the last one for that HostId.
  5. Staging sends webhooks only to domains we added. Ask us to add yours.