Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.novala.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

CodeMeaning
200 OKRequest succeeded.
201 CreatedResource created successfully.
400 Bad RequestRequest body failed validation.
401 UnauthorizedMissing or invalid API key.
403 ForbiddenAPI key does not have the required scope.
404 Not FoundResource not found or not accessible to this tenant.
409 ConflictConflict with existing data (for example, duplicate slug).
429 Too Many RequestsRate limit exceeded.
500 Internal Server ErrorUnexpected 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.