# API overview

The areas the API is split into, who calls each one, and how to get base URLs and the OpenAPI spec from the server's catalog.


The API covers the day-to-day work of a water or utility provider: customers, properties and accounts, meters and readings, billing, payments, prepaid credit, field operations and messaging. It is split into areas, each with its own base path, its own way of authenticating and its own audience. This page shows how to discover those areas and pick the right one.

## What you will build

A client with no hardcoded URLs: it reads the server's catalog, keeps the base URL of each area, and finds the OpenAPI spec from there.

## Prerequisites

- A sandbox environment or the address of an installation.
- `curl` and `jq`, or the `gotactl` CLI installed.
- For step 3, a secret test API key with the `business:customers:read` scope.

## 1. Read the API catalog

The catalog follows RFC 9727 and always lives at `/.well-known/api-catalog`. It needs no authentication.

```bash
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog"
```

The response is served as `application/linkset+json` and may be cached for 300 seconds (`Cache-Control: public, max-age=300`):

```json
{
  "linkset": [
    {"anchor": "$AUTH_API", "title": "auth", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$PUBLIC_API", "title": "public", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$BUSINESS_API", "title": "business", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$CONSUMER_API", "title": "consumer", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$PLATFORM_API", "title": "platform", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$PRIVATE_API", "title": "private", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$CONNECTOR_API", "title": "connector", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "https://api.gota.umbeluzi.com/api/openapi.json", "title": "openapi"}
  ]
}
```

✓ Checkpoint: `linkset` holds one entry per area, with its name in `title` and its base URL in `anchor`.

The paths above are the server's defaults. An operator can mount any area at a different path or leave it out, and the catalog always lists what is actually mounted. Resolve URLs by `title` instead of writing them into your code.

## 2. Pick the area

| Area (`title`) | Default path | Who calls it |
| :--- | :--- | :--- |
| `business` | `$BUSINESS_API` | The utility's own systems: ERP, accounting, automations and the staff dashboard. |
| `consumer` | `$CONSUMER_API` | Resident apps and portals, acting for the account holder. |
| `public` | `$PUBLIC_API` | Pages without a session: branding, client settings, estimates and service requests. |
| `connector` | `$CONNECTOR_API` | Payment and messaging connectors. |
| `auth` | `$AUTH_API` | Sign-up, sign-in and identity management. |
| `private` | `$PRIVATE_API` | External integrations: meter events, reading batches, integration health. |
| `platform` | `$PLATFORM_API` | Installation administration by the operator. |

To connect the utility's back-office systems, start with `business` and an API key (see [Authentication](/docs/getting-started/authentication)). Read its base URL from the catalog by `title`:

```bash
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog" | jq -r '.linkset[] | select(.title == "business") | .anchor'
```

✓ Checkpoint: the command prints one URL, the base of the area your system will call.

## 3. Call the area you picked

```bash
curl -sS "$BUSINESS_API/customers?limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: the response holds `data` with at most one customer and a `has_more` field.

## Test it

Follow the `service-desc` `href` to download the OpenAPI spec as JSON, or ask the CLI for it, which also finds it through the catalog:

```bash
gotactl openapi
```

## Next steps

- [Go from sign-up to your first request in the quickstart](/docs/getting-started/quickstart)
- [Choose the right authentication method](/docs/getting-started/authentication)
- [Create and manage API keys](/docs/getting-started/api-keys)
- [Browse the Business API reference](/docs/api/business)

