Ruche API

Your website, a spreadsheet, Zapier, Make, n8n or a system built for you talk to Ruche with a key. They read the schedule, clients and services, book, reschedule and cancel appointments, and receive a notice for every change.

On the Solo and Team plans, for the owner and the partners. Each key sees only its own business.

How to get the key

In the dashboard, open Settings and tap Integrations.
Tap Create key, give it a name and check what it can do.
Copy the key right away: it starts with rk_live_ and does not appear again.

Send the key in the Authorization: Bearer header of each request. Call the API from your system's server, never from a page that a visitor's browser downloads: there the key would be in plain view.

What each key can do

When you create the key, you check the scopes. A route without the scope responds 403.

appointments.read: See appointments: date, time, service, who serves and the name of who is coming. Never the appointment code.
appointments.write: Book into an open time, reschedule and cancel with the reason, under the same rules and emails as the dashboard.
clients.read: See clients: name, phone, email and birthday. Never notes, records or photos.
clients.write: Add a new client. Existing ones do not change through the API.
services.read: See services, duration and price.
payments.read: Ver os pagamentos, os valores e o horário ligado, sem dados bancários.
sales.read: Ver as vendas e os itens, sem custos nem notas internas.

Write without repeating

Booking, rescheduling, canceling and adding require the Idempotency-Key header, with a new value for each action (a UUID works). If the network drops and your system sends again with the same key and the same body, Ruche returns the same response, without booking twice. The same key with a different body responds 409. The response is kept for 24 hours.

Notices to your system

Under Integrations, enter an https address and check when to notify. Each notice is a JSON POST with the type, a unique id and the id and time of what changed. Name, phone and amounts never go in the notice: your system fetches the rest through the API, with a key.

GET /payments/:id e GET /sales/:id mostram o objeto do aviso. As listas GET /payments e GET /sales aceitam updatedSince, limit (1 a 100) e cursor; nextCursor nulo indica o fim. Valores em centavos, com a moeda do negócio. Uma venda com paymentPending ainda está a receber. Somente leitura.

appointment.createdAppointment booked
appointment.confirmedAppointment confirmed
appointment.cancelledAppointment canceled
appointment.rescheduledAppointment rescheduled
client.createdNew client
payment.receivedPayment received
sale.createdSale recorded

Each notice is signed with HMAC SHA-256 in the x-ruche-signature header, using the address's secret. Check it before trusting it.

Examples

Listar pagamentos

curl "https://api.ruche.my/v1/api/payments?limit=50" -H "Authorization: Bearer rk_live_..."

Buscar o pagamento do aviso payment.received

curl "https://api.ruche.my/v1/api/payments/ID_DO_PAGAMENTO" -H "Authorization: Bearer rk_live_..."

Listar vendas

curl "https://api.ruche.my/v1/api/sales?limit=50" -H "Authorization: Bearer rk_live_..."

Buscar a venda do aviso sale.created

curl "https://api.ruche.my/v1/api/sales/ID_DA_VENDA" -H "Authorization: Bearer rk_live_..."

Test the key

curl https://api.ruche.my/v1/api/me \
  -H "Authorization: Bearer rk_live_..."

October's appointments

curl "https://api.ruche.my/v1/api/appointments?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer rk_live_..."

Book an appointment

curl -X POST https://api.ruche.my/v1/api/appointments \
  -H "Authorization: Bearer rk_live_..." \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4e1a-9c55-2d8f0b4a7e13" \
  -H "Content-Type: application/json" \
  -d '{"staffId":"<id>","serviceId":"<id>","startAt":"2026-10-06T10:00:00-03:00",
       "client":{"name":"Carla Nunes","phone":"+5511988887766"}}'

Cancel with the reason

curl -X POST https://api.ruche.my/v1/api/appointments/<id>/cancel \
  -H "Authorization: Bearer rk_live_..." \
  -H "Idempotency-Key: 0b9e7d4c-58a2-4f61-8d3e-a1c7b2f60d94" \
  -H "Content-Type: application/json" \
  -d '{"reason":"A cliente pediu pelo site"}'

Limits and responses

Up to 120 requests per minute per key. Beyond that, the response is 429 with Retry-After.
401: key missing, wrong or revoked.
402: the business's plan does not include integrations.
403: the key does not have the route's scope.
409: time already taken, client that already exists or Idempotency-Key repeated with a different body.

OpenAPI specification

All routes, fields and responses are in the OpenAPI 3.1 file, generated from the same schemas that validate requests. Import it into Postman, Insomnia or the code generator you use.

Download openapi.json Step by step in the help center