API reference

The ByDomu API v1 is REST with JSON. This reference is generated from the OpenAPI spec, which in turn comes from the routes’ code: every endpoint lists its parameters, the permission it needs and examples. There is no official SDK; you can generate your own client from the spec.

Base URL

https://api.bydomu.com/v1

OpenAPI

openapi.json · v3.1.0

This reference is generated from the API’s code, so descriptions are in Spanish. Names, parameters and examples are the same in every language.

Authentication

The key goes in the X-API-Key header (Authorization: Bearer is not accepted). You create it in ByDomu under Settings › API Keys, and the full key is shown only once.

cURL

curl https://api.bydomu.com/v1/me \
  -H "X-API-Key: $BYDOMU_API_KEY"

domu_pk_live_publishable

For websites and the browser. Only: portal:read, leads:write, booking:write, finder:write, events:write.

domu_sk_live_secret

Server-side only: with an Origin header (browser) it returns 403 SECRET_KEY_IN_BROWSER. Any permission.

domu_live_legacy

Keys created before key types existed. They keep working the same.

Access levels

LevelPlansHow to get it

1Publishable keys300 requests and 60 writes per minute · up to 5 keysAny paid planNo request

2Read-only secret keys60 requests per minute · up to 2 keysBusiness · EnterpriseAutomatic

3Writes, messages, webhooks and higher limitsTailored to what’s approvedAny paid planSupport review

Pagination

Lists take page (from 1) and pageSize, and respond with the data and the total. Each endpoint states its maximum pageSize. Contacts, deals and tasks also accept a cursor.

JSON

{
  "data": [ … ],
  "meta": { "total": 64, "page": 1, "pageSize": 12, "totalPages": 6 }
}

Errors

Always with the same shape. Data that fails schema validation returns 400 with the list of issues.

JSON

{
  "error": {
    "code": "FORBIDDEN",
    "message": "La API key no tiene el scope requerido: contacts:read"
  }
}

400VALIDATION_ERRORInvalid input

401UNAUTHORIZEDMissing or invalid key

402PAYMENT_REQUIREDAccount is read-only: write rejected

403FORBIDDENThe key lacks that permission

403SECRET_KEY_IN_BROWSERSecret key used from a browser

403API_ACCESS_REQUIREDThe account’s access level doesn’t allow this key

403PLAN_LIMIT_REACHEDA plan limit was reached

404NOT_FOUNDResource not found

409IDEMPOTENCY_CONFLICTIdempotency-Key reused with a different body

429RATE_LIMITEDPer-minute limit exceeded

Limits

A publishable key gets 300 requests and 60 writes per minute; a secret key, 60 and 30. Support can approve more. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; when you go over, 429 RATE_LIMITED with Retry-After.