> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Base URL, request/response conventions, and how the tenant API is organized.

The Alforse API is a tenant-scoped HTTP API mounted under one global prefix. Deals, the tenant
administration experience, and supporting backend services call this same API; direct API
access is available on the `business` plan and above (see
[Plans & Editions](/concepts/plans-and-editions)).

## Base URL

| Environment            | Base URL                                  |
| ---------------------- | ----------------------------------------- |
| Alforse Cloud          | `https://api.alforse.com/api/v1`          |
| Enterprise self-hosted | `https://api.your-company.example/api/v1` |

Every path in this reference is relative to the base URL. For Alforse Cloud,
`POST /contracts` means
`POST https://api.alforse.com/api/v1/contracts`.

## Tenant-scoped API access

Public API access is tenant-scoped — see [Tenants & Data Boundaries](/concepts/tenants-and-platform):

All documented endpoints require either a public auth flow or a tenant access token
(`scope: "tenant"`). Tenant tokens carry `tenantId`, `roleCode`, and `subjectScope` claims and
cannot be reused across organizations.

Start with [Authentication](/api-reference/authentication).

## Request format

* All request bodies are JSON (`Content-Type: application/json`), up to 16 MB.
* Every DTO is validated with `whitelist` **and** `forbidNonWhitelisted` enabled: fields that
  aren't part of the documented request body cause a `400 Bad Request` instead of being silently
  dropped. Double-check field names if you get an unexpected 400.
* Query parameters on list endpoints are validated the same way as bodies.

## Pagination

List endpoints share one convention:

<ParamField query="page" type="integer" default="1">
  1-indexed page number.
</ParamField>

<ParamField query="pageSize" type="integer" default="20">
  Items per page, maximum `200`.
</ParamField>

## Errors

Most framework-level errors use the NestJS default shape:

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed" ,
  "error": "Bad Request"
}
```

`message` is either a string or an array of validation messages (one per invalid field) for
`400` responses from a DTO validation failure.

Domain errors can also include a stable business code:

```json theme={null}
{
  "error": {
    "code": "PLAN_FEATURE_NOT_ENABLED",
    "message": "Feature is not enabled for this plan",
    "details": {
      "feature": "workflowAutomation"
    }
  }
}
```

Use the HTTP status for transport behavior and `error.code` for product-specific handling.
See [Errors & Codes](/api-reference/errors) for the complete public reference.

## Health check

`GET /health` is unauthenticated and safe to poll for uptime monitoring:

```json theme={null}
{
  "status": "ok",
  "edition": "saas",
  "platformDb": "up",
  "tenantDb": "up",
  "time": "2026-07-03T12:00:00.000Z",
  "isolate": "a1b2c3"
}
```

`status` is `"degraded"` if either database is unreachable.