# Create a gRPC API

A gRPC API gets its operations from its service definitions: every unary method of every service becomes an operation. The **New API** wizard asks where the definitions come from before it asks for code.

## Before you begin

- A model provider connected to your workspace. See [Connect your model provider](https://docs.faustine.ai/get-started/connect-your-ai-provider/).
- One of these: the address of a running server with server reflection on, the `.proto` files, or the repository that contains them.

## Choose the schema source

| Source | What Faustine reads | Choose it when |
| --- | --- | --- |
| **Fetch via server reflection** | The descriptors your live server returns over `grpc.reflection.v1` or `v1alpha` | Reflection is on in a deployment Faustine can reach. This is the most reliable source. |
| **Upload .proto files or a zip** | One or more `.proto` files, or a zip with the whole proto tree, up to 5 MB | Reflection is off. |
| **Analyze the repository** | The `.proto` files in the repository and their imports | The files live with the code. |

When a repository is also connected, the analysis checks it too. Reflection and `.proto` files take precedence over what the code says.

## Create the API

1. In the portal, go to [**APIs**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis) and select **New API**.
2. In **API type**, select **gRPC**.
3. In **Language & framework**, select your framework, or **Other / not listed**.
4. In **Details**, enter a **Name** and a **Namespace**, then select **Continue**. The namespace cannot be changed later.
5. In **Schema source**, select one of the three sources:
   - **Fetch via server reflection**: under **Authentication**, choose how the API signs in. Then enter the connection's **Name**, the address and transport of the server, and the credential values. This becomes the API's first connection.
   - **Upload .proto files or a zip**: select **Choose files**.
   - **Analyze the repository**: you pick the repository in the next step.
6. Select **Continue**.
7. In **Repository (optional)**, connect the repository and select **Continue**, or select **Skip**. If the repository is the schema source, the step is named **Connect your code** and is required.
8. If you connected a repository, choose **Automatic** or **Manual** in **Keep the API up to date**.
9. In **Review & analyze**, select **Create & start analysis**.

The analysis page opens. When the run finishes, select **Open the API page**. The **Operations** tab lists one operation for each unary method.

## What the repository adds

With the code connected, the analysis also reads the service handlers. It uses them to decide which methods are destructive, and the API can update on every push. Without a repository, the contract comes from the definitions alone.

## Change the source later

**Re-analyze** in the **Actions** menu asks **Where the contract comes from** each time: the code or uploaded files, or **The live service (reflection)** through one of the API's connections. To replace uploaded files, use **Settings** > **Code & contract** > **Proto files**. The setting accepts a single `.proto` or a zip with the whole proto tree, and the new files take effect on the next analysis.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `The files add up to more than 5 MB.` | The selected `.proto` files are over the limit together. | Upload only the proto tree of this service, or use **Analyze the repository**. |
| A streaming method is not in **Operations** | The analysis derives unary methods only. | None. Streaming methods are not operations. |

## Next steps

- [gRPC](https://docs.faustine.ai/technologies/grpc/): how Faustine calls a gRPC service.
- [Operations](https://docs.faustine.ai/apis/operations/): review the methods the analysis found.
- [Connections](https://docs.faustine.ai/apis/connections/): add the other deployments of the service.