# Create an API

The **New API** wizard creates an API and starts its analysis. This page covers a REST API that is one service. For other cases, see [Create a GraphQL API](https://docs.faustine.ai/apis/create-a-graphql-api/), [Create a gRPC API](https://docs.faustine.ai/apis/create-a-grpc-api/) and [Analyze an API made of several services](https://docs.faustine.ai/apis/several-services/).

## Before you begin

- A model provider connected to your workspace. The analysis runs on it. See [Connect your model provider](https://docs.faustine.ai/get-started/connect-your-ai-provider/).
- The backend's code, in a GitHub, GitLab or Bitbucket repository that Faustine can read, or as a ZIP. See [Connect GitHub](https://docs.faustine.ai/technologies/github/).

## Describe the API

To start the wizard:

1. In the portal, go to [**APIs**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis) and select **New API**.
2. In **API type**, select **REST**. If you do not know the protocol, select **Not sure** and the analysis detects it.
3. In **Architecture**, select **One service**, then **Continue**. A backend-for-frontend that declares its own routes is one service.
4. In **Language & framework**, select your framework, or **Other / not listed**. The choice is a hint for the analysis.
5. In **Details**, enter a **Name** and a **Namespace**, then select **Continue**.

The namespace starts every operation key, as in `billing.invoices.list`. It accepts lowercase letters and digits, and it cannot be changed after the API is created. The wizard reports a namespace that another API of your workspace already uses.

## Connect your code

In **Connect your code**, choose where the code comes from.

**Repository**

1. Select the provider: GitHub, GitLab or Bitbucket.
2. Select the connection, then the **Repository** and the **Branch**. All three are required.
3. If the API lives in a folder of a monorepo, enter the folder in **API path**.

**ZIP**

1. Select **Upload a ZIP**.
2. Drop the archive, or choose it. Zip the source without `node_modules`, `.git` or build output. A ZIP can be up to 500 MB.
3. If the API lives in a folder of the archive, select it in **Folder to analyze**.
4. To keep the code after the analysis, turn on **Keep the code after the analysis**.

Faustine deletes the archive when the analysis finishes unless **Keep the code after the analysis** is on. Without the stored code you cannot re-analyze the API or open the Advanced editor until you upload it again.

**Anything we should know about this API?** is optional. The analysis reads it before it reads the code, so use it for vocabulary, routes to skip and unusual error handling. Select **Continue**.

## Add a spec and choose how the API updates

1. In **Spec (optional)**, upload an OpenAPI or Swagger file (`.json` or `.yaml`, up to 5 MB), or select **Skip**. With a spec, the analysis takes routes and schemas from it and reads the code for rules and authentication.
2. In **Keep the API up to date**, select **Automatic** or **Manual**, then **Continue**. This step appears only when the code comes from a repository. See [Keep the API up to date](https://docs.faustine.ai/apis/keep-up-to-date/).
3. In **Review & analyze**, check the summary and select **Create & start analysis**.

The portal opens the analysis page, where the run shows its stages and its log. You can leave the page while it runs. When the run finishes, select **Open the API page**.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `The namespace "…" is already used by another API.` | Namespaces are unique in a workspace. | Enter another namespace in **Details**. |
| `The file is larger than 5 MB.` | The spec file is over the limit. | Upload a smaller spec, or skip the step and let the analysis read the code. |
| **Keep the API up to date** does not appear | The code is a ZIP, which has no branch to watch. | Update the API with **Upload a new version** in the **Actions** menu. |

## Next steps

- [The analysis](https://docs.faustine.ai/apis/analysis/): what the run does and how to read its result.
- [Review and test an operation](https://docs.faustine.ai/apis/test-an-operation/): check what the analysis found.
- [Add a connection](https://docs.faustine.ai/apis/add-a-connection/): tell Faustine where the backend runs.
- [Add an API to a gateway](https://docs.faustine.ai/agent-gateway/add-an-api/): serve the operations to AI clients.