> For the complete documentation index, see [llms.txt](https://docs.scaleconnect.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleconnect.com.au/api/rest-api.md).

# REST API

{% @scale-docs-page-title/page-title title="REST API" %}

{% hint style="warning" %}
**Confirm before publishing:** which R16 operations enter the public contract, the public base URL, authentication and scopes, request/response schemas, pagination, error envelopes and compatibility policy. The generated R16 references are internal snapshots; the proposed `/v1/integrators/*` routes are not established as deployed public endpoints.
{% endhint %}

Use the reference that matches the system you are integrating with.

| Reference                                                       | What it documents                                       | Intended audience                             |
| --------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------- |
| [ScaleConnect REST API](/api/rest-api/scaleconnect-rest-api.md) | Scoped broker, client-book, sync and webhook operations | Approved integrators and broker developers    |
| [ScaleApp REST API](/api/rest-api/scaleapp-rest-api.md)         | The current R16 application backend and DTOs            | Internal teams reviewing the source contract  |
| [ScaleAI REST API](/api/rest-api/scaleai-rest-api.md)           | FastAPI agent engine routes and models                  | Internal teams reviewing AI service contracts |

## Request conventions

Use HTTPS and JSON for ordinary REST bodies. Put credentials in `Authorization`; send `Content-Type: application/json` when a body is present. Use ISO 8601 timestamps with an explicit timezone. Treat an omitted field, a `null` field and a zero value as different states unless the operation says otherwise.

```http
GET /v1/integrators/clients?updatedSince=2026-10-01T00:00:00Z HTTP/1.1
Host: <approved-api-host>
Authorization: Bearer sc_live_<secret>
Accept: application/json
```

The example shows the **intended public route shape**. Use the generated reference for an internal R16 call; an internal route is not automatically supported for partners.

## Versioning and compatibility

`/v1/` is the intended path version for the first public contract. Compatible additions may add optional response fields or new operations. A breaking change to a published path, required input, field meaning or error contract needs a versioned migration and overlap period. Documentation edits do not create or version backend routes.

## Responses, errors and pagination

Use the status, media type and schema shown on each operation. A list endpoint must state its cursor or page parameters and response metadata; no one pagination scheme should be inferred for all R16 endpoints. Handle `401` by renewing credentials, `403` by correcting scopes or resource access, `429` by backing off, and `5xx` with bounded retries for safe or idempotent operations. For writes, use an idempotency key or read-after-write pattern only where that operation defines one.

## From internal reference to public contract

1. Select the operations that have a partner use case.
2. Freeze method, path, request, success response, errors and scopes from deployed behaviour.
3. Remove internal-only fields from a **separate public schema and serializer**; changing the documentation alone does not remove them from a response.
4. Test the published schema against the deployed route.
5. Publish the selected reference after the access model and contract are approved.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scaleconnect.com.au/api/rest-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.