Overview

A project is the top-level workspace in Shift-Left API. It holds the API definition you import, the endpoints discovered from it, the tests built on those endpoints, the environments and credentials used to reach your API, and the results of every run.

Everything else in the product hangs off a project. It's the first thing you create, and it's the boundary that settings, environments, and authentication apply to.

Inside a project, work is organized in three levels:

Level	What it is
Project	The workspace. Owns settings, environments, and authentication profiles.
Feature	A grouping of endpoints, created from the tags or groups in your API specification.
Endpoint	A single operation, such as `GET /orders/{id}`. Tests attach to endpoints.

Before you begin

Complete Getting started and Initial configuration first.
Have your API specification ready — an OpenAPI/Swagger document, a WSDL, or a GraphQL schema. You'll import it immediately after creating the project.
You need permission to create projects. See Role permissions.

Create the project

In the left sidebar, select Project.
Fill in the two fields:

Field	What to enter
Name	A clear name for the API or service this project covers.
Description	A short summary of the project's purpose and scope.

Confirm to create the project.

Shift-Left API then opens the API import flow so you can populate the project straight away — see Project operations.

Both fields are editable later in Project settings, so nothing here is permanent.

Choosing a name and scope

Scope is the decision that most affects how usable the workspace is later, because environments, authentication profiles, and permissions all live at project level.

Scope a project to one API boundary — one service, one contract. If two APIs have different base URLs, different credentials, and different owners, they want different projects.
Decide whether the project is environment-specific. If it is, put the environment in the name (Payments API - QA). If instead you plan to run one project across dev, QA, and staging, leave the environment out of the name and use the environment list inside Project settings — that's what it's for.
Write a description that answers "what is this, and who owns it?" It's what a teammate reads when deciding whether they're in the right workspace.

Resist making one project for everything. A project holding several unrelated APIs ends up with a confusing environment list and authentication profiles that only apply to some of its endpoints.

What happens next

Once the project exists:

Import your API definition — Project operations. This creates the features and endpoints.
Configure environments and authentication — Project settings. Tests can't reach your API until base URLs and credentials are set.
Browse what was imported — Managing projects.
Check the endpoints resolve — Validate endpoints.
Create tests — by hand with Test case, or generated with AI-generated tests.
Run them — Test run.

Steps 1–2 are one-time setup. Steps 5–6 are the loop you'll live in.

How many projects should you have?

The most common mistake is guessing at this and reorganizing later, so it's worth a moment up front.

One project per API contract. If you own three services with three specs, that's three projects — regardless of whether they ship together. Each gets its own base URLs, its own credentials, and its own endpoint tree, and none of those are things you want to share across unrelated services.

Environments live inside a project, not as separate projects. If your Payments API runs in dev, QA, and staging with the same contract and different hosts, that's one project with three environments — not three projects. Creating Payments - Dev and Payments - QA as separate projects means importing the same spec twice, maintaining two copies of every test, and having them drift.

The exception is when the environments genuinely differ — a legacy staging service with a different contract, say. Different contract, different project.

Split when ownership splits. If two teams need different permissions over different endpoints, projects are the boundary that gives you that. See Role permissions.

Troubleshooting

No option to create a project — project creation is permission-gated. Ask an administrator to check your role in Role permissions.
The import flow didn't start after creating the project — creation and import are separate steps; you can import at any time from the project. See Project operations.
You picked the wrong name — edit it in Project settings.
You created one project per environment and now maintain duplicate tests — consolidate onto one project with multiple environments. Import the spec once, then add environments in Project settings.

Create Your First Project in Shift-Left API