> For the complete documentation index, see [llms.txt](https://docs.pal.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pal.aic.io/using-pal.net/platform-api.md).

# Platform API

The generated platform surface provides strongly typed C# access to the public operations in the pinned upstream baseline. It is the complete escape hatch for capabilities that do not yet have a reviewed ergonomic façade.

## Capability clients

The generated registration exposes scoped clients for these capability families:

`Admin`, `AipAgents`, `Audit`, `Checkpoints`, `Connectivity`, `DataHealth`, `Datasets`, `Filesystem`, `Functions`, `MapRendering`, `MediaSets`, `Models`, `Notepad`, `Observability`, `Ontologies`, `Orchestration`, `Sds`, `SqlQueries`, `Streams`, `ThirdPartyApplications`, and `Workbench`.

Each generated client has operation-specific request builders, typed response models, raw operation descriptors, and documented error metadata. Generated models live under `PAL.Core.Models.Domain.Generated.Platform` and generated clients under `PAL.Core.Services.Domain.Generated.Platform`.

## Operation pattern

The exact generated method name follows the upstream operation name. The common shape is:

```csharp
var client = scope.ServiceProvider.GetRequiredService<DatasetsPlatformClient>();

var request = DatasetGetDatasetRequest
    .CreateBuilder("ri.dataset.example")
    .Build();

var response = await client.DatasetGetDatasetAsync(request, cancellationToken);
```

Required path and body values are constructor or builder requirements. Optional query/header values are explicit builder settings. If an operation is streaming or paginated, its generated return type reflects that contract rather than silently buffering it.

Inspect generated source and IntelliSense for the authoritative request type and method name for a particular operation. Do not hand-edit `*.g.cs` files; regenerate them from the pinned source.

## Raw operation escape hatch

Generated operation descriptors can be executed through `IPalPlatformOperationClient` when a new operation needs low-level access before a façade is added:

```csharp
var request = new PalPlatformOperationRequest()
    .WithPathParameter("datasetRid", datasetRid)
    .WithQueryParameter("branchName", branchName)
    .WithJsonBody(body);

var response = await operationClient.SendAsync(
    DatasetsPlatformOperations.DatasetGetDataset,
    request,
    cancellationToken);
```

Use `SendJsonAsync<TResponse>` for a required JSON response and `SendOptionalJsonAsync<TResponse>` when an empty body is valid. Use `StreamAsync` for binary, event, or large responses.

## Parameter helpers

The operation request extensions provide:

* `WithPathParameter` for one serialized path value;
* `WithQueryParameter` for scalar or repeated collection values;
* `WithQueryParameterReplacing` to replace all values for a query name;
* `WithHeaderParameter` for operation-specific headers;
* `WithJsonBody` for a generated or anonymous JSON body.

Null optional query values are omitted. Path and header parameters must serialize to exactly one non-null value. Restricted headers such as `Authorization`, `Host`, and `Content-Length` remain under PAL.NET control.

## Generated guarantees

Every public operation executes through the same token, licence, cancellation, diagnostics, error mapping, and retry pipeline. The current conformance evidence records 321 generated public operations, 41 paginated operations, and 22 streaming operations.