Novala REST API — base URLs, errors, and pagination

The Novala REST API gives you programmatic access to every module in the platform — contacts, leads, pipeline deals, inspections, invoices, and bookings. All requests and responses use JSON, and every endpoint is scoped to your tenant so data from different organizations never mixes.

Base URL

Novala runs each tenant on a dedicated subdomain. Use the subdomain form for all v1 endpoints:

https://{tenant}.novala.ai/api/v1

Replace {tenant} with your tenant slug (for example, acme → https://acme.novala.ai/api/v1). Endpoints that are not yet under /v1 use the same subdomain base without the version prefix:

https://{tenant}.novala.ai/api

All examples in this reference use app.novala.ai as a placeholder. Replace it with your tenant subdomain when making real requests.

Authentication

Every request to a protected endpoint must include an Authorization header carrying a bearer API key:

Authorization: Bearer sk_live_…

See the Authentication page for how to issue keys, select scopes, and rotate credentials.

Pagination

The API uses two pagination styles depending on the endpoint.

Offset-based pagination

Most list endpoints accept page (1-based, default 1) and limit (default 25, max 100) query parameters. The response envelope looks like:

{
  "data": [...],
  "total": 142,
  "page": 1,
  "pageSize": 25
}

Cursor-based pagination

Newer endpoints (leads, and future additions) use keyset/cursor pagination. Pass limit and an opaque cursor string obtained from the previous response:

{
  "data": [...],
  "nextCursor": "eyJpZCI6Ii4uLi4iLCJjcmVhdGVkQXQiOiIuLi4ifQ==",
  "hasMore": true
}

When hasMore is false or nextCursor is null, you have reached the last page.

Error responses

All errors return a JSON body with an error field:

{
  "error": "Contact not found"
}

Validation errors return additional detail:

{
  "error": "Validation failed",
  "fields": [
    { "field": "email", "message": "Invalid email address" }
  ]
}

HTTP status codes

Code	Meaning
`200 OK`	Request succeeded.
`201 Created`	Resource created successfully.
`400 Bad Request`	Request body failed validation.
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	API key does not have the required scope.
`404 Not Found`	Resource not found or not accessible to this tenant.
`409 Conflict`	Conflict with existing data (for example, duplicate slug).
`429 Too Many Requests`	Rate limit exceeded.
`500 Internal Server Error`	Unexpected server error.

Rate limiting

API requests are rate-limited per tenant. When you exceed the limit, the server returns 429 Too Many Requests. Implement exponential backoff and retry logic in your integration.

Versioning

Endpoints under /api/v1/ follow a stable versioning contract. Breaking changes are never made within a major version. Endpoints outside /v1/ (inspections, invoices, bookings) are production-stable but may receive additive changes without a version increment.

​Base URL

​Authentication

​Pagination

​Offset-based pagination

​Cursor-based pagination

​Error responses

​HTTP status codes

​Rate limiting

​Versioning

Base URL

Authentication

Pagination

Offset-based pagination

Cursor-based pagination

Error responses

HTTP status codes

Rate limiting

Versioning