# gRPC

Start with [Connect via API](../connect-api.md) to create a Platform API token. gRPC-Web clients use `https://reconstruct.dev`. Native gRPC connects to `reconstruct.dev:443` over TLS and uses the method path generated from the proto service name. Each call needs `authorization: Bearer <token>` metadata.

`GetCaptureOptions` returns supported type IDs and environments; clients
should not keep their own fixed list. `CatalogPlatform.view` is the platform type (`desktop`/`mobile`), and
`CatalogPlatform.implementation` is the environment. Desktop supports
`web/macos/windows/linux`; mobile supports `web/ios/android`. `captured` indicates
stored availability. MCP uses `platform`/`environment` for that same selection;
its page `view` identifies a saved profile. See the [MCP catalog](../mcp-tools.md).

## Download the contract

```bash
curl -fsSL https://reconstruct.dev/docs/proto/platform.proto -o platform.proto
```

The [client-facing contract](pathname:///proto/platform.proto) has the same service, messages, and field numbers as the server contract. Its HTTP annotations are omitted so client generation does not require Google's API annotation protos.

| RPC | Request | Result |
|---|---|---|
| `ListCatalogs` | `page_size`, optional `page_token` | `catalogs[]`, optional `next_page_token` |
| `GetCaptureOptions` | Empty request | Supported platform/environment IDs, defaults and request platform options; no authentication or metering. |
| `GetCatalog` | `catalog_id`, optional `version` | Metadata, selected `version`, published `versions[]`, `screens[]`, platform/language options |
| `GetCatalogInsights` | `catalog_id`, optional `locale`, `view`, `implementation`, `section`, `version` | `version`, `technologies[]`, `rendering`, `fonts[]`, `text_styles[]`, `assets[]`, `color_themes[]`, `page_count` |

Use `next_page_token` as the next call's `page_token` to continue through the list. Get catalog IDs from `ListCatalogs`.

The contract also includes `GetCatalogFile` (bytes and content type, optional `version`), `CreateRequest`, `ListRequests`, `GetRequest`, and the account, appearance, avatar and personal-token operations listed in the [REST guide](./rest.md). The same account access requirements apply to both API styles. `ListCatalogs` supports the platform's search, sort and repeated filters documented there.

`WatchCatalogs` streams `changed` and `revision`; pass `catalog_id` for one catalog or omit it for the list, and reuse the last `revision` when reconnecting. `WatchRequests` streams invalidations for the caller's requests. Refresh the corresponding data when `changed` is true. These streams use gRPC/gRPC-Web and have no HTTP annotation.

## Generate a client

- [Python](./grpc/python.md)
- [C#](./grpc/csharp.md)
- [TypeScript](./grpc/typescript.md)
- [Go](./grpc/go.md)
- [Rust](./grpc/rust.md)
- [Java](./grpc/java.md)
- [C++](./grpc/cpp.md)

## Try a call with grpcurl

From the directory containing `platform.proto`, with `CR_RECONSTRUCT_API_TOKEN` set:

```bash
grpcurl \
  -import-path . -proto platform.proto \
  -H "authorization: Bearer ${CR_RECONSTRUCT_API_TOKEN}" \
  -d '{"pageSize":10}' \
  reconstruct.dev:443 \
  reconstruct.platform.v1.PlatformService/ListCatalogs
```

Use a hostname and port for the native gRPC target, without a URL path.

## Account usage and billing

Manage your subscription and review usage in the Platform’s account settings.
Personal API and MCP tokens provide access to catalog and request operations;
they cannot be used to manage account billing.