Documentation Index
Fetch the complete documentation index at: https://docs.gateways.app/llms.txt
Use this file to discover all available pages before exploring further.
Projects and Environments API
Overview
The Projects and Environments API provides endpoints for managing projects and their associated environments. Projects are top-level containers for organizing your infrastructure resources, and environments (likeproduction, staging, development) allow you to manage resources across different deployment stages.
Base Endpoint: /api/projects
All endpoints require authentication.
Workspace Integration: Projects are organized within workspaces. Each project belongs to a workspace, and workspace membership determines access to projects. To list projects for a specific workspace, use GET /api/workspaces/:workspaceSlug/projects (see Workspaces API).
Plan Restrictions: Project and environment creation is subject to your workspace’s pricing plan limits. See the Pricing Plans API documentation for details. If you exceed your plan limits, you’ll receive a 403 Forbidden error.
Projects
Projects are user-owned containers that organize your infrastructure resources. Each project can have multiple environments and can be connected to a cloud provider account.Important Notes
- Project slugs are globally unique (across all users) and are automatically generated from the project name
- Slug cannot be provided in request body - it is always auto-generated from the name field
- Projects are associated with workspaces. All projects belong to a workspace, and workspace membership determines access
- The first project created in a workspace is automatically set as the default project for that workspace
- To preview the slug that will be generated, use the JavaScript function provided below
- Project deletion is soft delete (project is marked as inactive)
- Note: To list projects for a specific workspace, use
GET /api/workspaces/:workspaceSlug/projects. See the Workspaces API documentation.
Check Project Name Availability
Check if a project name (slug) is available globally before creating a project. Endpoint:GET /api/projects/check-name
Authentication: Required
Query Parameters:
name(required): The project name to check
name: The trimmed name that was checkedslug: The generated slug from the nameavailable:trueif the slug is available (not taken),falseif it’s already in use
400 Bad Request: Missing or invalidnamequery parameter401 Unauthorized: Missing or invalid authentication token500 Internal Server Error: Failed to check name availability
Create Project
Create a new project in a workspace. Endpoint:POST /api/workspaces/:workspaceSlug/projects
Authentication: Required
Parameters:
workspaceSlug(path) - The slug of the workspace where the project will be created
- Projects are created within a workspace. The user must be a member of the specified workspace and have permission to create projects.
- Slug is automatically generated from name - it cannot be provided in the request body
- Name must be between 1 and 100 characters
- Description must be at most 350 characters (optional)
- Use the JavaScript function below to preview the slug that will be generated
400 Bad Request: Missing required fields (e.g.,name), invalid name length (must be 1-100 characters), or invalid description length (must be at most 350 characters)401 Unauthorized: Missing or invalid authentication token403 Forbidden: Plan limit exceeded (e.g., maximum number of projects reached) or user does not have access to the workspace. See Pricing Plans API for details.404 Not Found: Workspace does not exist500 Internal Server Error: Failed to create project
Slug Generation
Slugs are automatically generated from names using the following JavaScript function. You can use this function in your frontend to preview the slug that will be generated:"My Awesome Project"→"my-awesome-project""Production Environment"→"production-environment""Dev_Test"→"dev-test""API-Server@2024"→"api-server2024""---Special---"→"special"" Spaces "→"spaces"
- Name must be between 1 and 100 characters
- Any characters are allowed in the name - the slug will be generated automatically
List Projects
Get all projects for the authenticated user across all workspaces they have access to. Endpoint:GET /api/projects
Authentication: Required
Query Parameters:
include_inactive(optional): Include inactive projects. Set to"true"to include soft-deleted projects. Default:false
GET /api/workspaces/:workspaceSlug/projects (see Workspaces API).
Example Request:
Get Project Usage
Get usage statistics for a project, including current usage and plan limits for environments and resources. Endpoint:GET /api/projects/:projectSlug/usage
Parameters:
projectSlug(path) - The slug of the project
project- Project details (id, slug, name)plan- Current pricing plan for the workspace (id, slug, name)usage.environments- Environment usage in this project (current count, limit per project, percentage used, unlimited flag)usage.resources.total- Total resource count across all environments in this project (from unifiedresourcestable)usage.resources.limit- Maximum resources allowed per projectusage.resources.percentage- Percentage of project resource limit usedusage.resources.unlimited- Whether resources per project are unlimited
resources table.
Note:
- If
limitisnull, the plan has unlimited resources for that category - If
unlimitedistrue, there is no limit enforced percentageis calculated as(current / limit) * 100and capped at 100
401 Unauthorized- User ID not found400 Bad Request- Invalid project slug404 Not Found- Project does not exist403 Forbidden- User does not have access to this workspace500 Internal Server Error- Failed to retrieve project usage
Get Project
Get details of a specific project by slug. Endpoint:GET /api/projects/:projectSlug
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the project
400 Bad Request: Invalid project slug401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project404 Not Found: Project does not exist500 Internal Server Error: Failed to retrieve project
Update Project
Update an existing project. Endpoint:PATCH /api/projects/:projectSlug
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the project to update
- The
isDefaultandisActivefields cannot be updated through this endpoint. Use theset-defaultendpoint to change the default project, and these fields are managed automatically by the system. - Description must be at most 350 characters
400 Bad Request: Invalid project slug or no fields provided to update401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project404 Not Found: Project does not exist500 Internal Server Error: Failed to update project
Set Default Project
Set a project as the user’s default project. Endpoint:PATCH /api/projects/:projectSlug/set-default
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the project to set as default
400 Bad Request: Invalid project slug401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project404 Not Found: Project does not exist500 Internal Server Error: Failed to set default project
Delete Project
Delete a project (soft delete - marks project as inactive). Endpoint:DELETE /api/projects/:projectSlug
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the project to delete
400 Bad Request: Invalid project slug401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project404 Not Found: Project does not exist500 Internal Server Error: Failed to delete project
Environments
Environments are deployment stages within a project (e.g.,production, staging, development). They help organize resources by their deployment context.
Important Notes
- Environment slugs are unique within a project and are automatically generated from the environment name
- Slug cannot be provided in request body - it is always auto-generated from the name field
- A default
masterenvironment is automatically created when you create a project - Only one environment per project can be marked as default
- Environment deletion is soft delete (environment is marked as inactive)
- To preview the slug that will be generated, use the JavaScript function in the “Slug Generation” section above
Check Environment Name Availability
Check if an environment name (slug) is available within a project before creating an environment. Endpoint:GET /api/projects/:projectSlug/environments/check-name
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the project
name(required): The environment name to check
name: The trimmed name that was checkedslug: The generated slug from the nameavailable:trueif the slug is available within the project (not taken),falseif it’s already in useprojectId: The ID of the projectprojectSlug: The slug of the project
400 Bad Request: Missing or invalidnamequery parameter or invalid project slug401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t have access to this workspace404 Not Found: Project does not exist500 Internal Server Error: Failed to check name availability
Create Environment
Create a new environment in a project. Endpoint:POST /api/projects/:projectSlug/environments
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the project
- Slug is automatically generated from name - it cannot be provided in the request body
- Name must be between 1 and 100 characters
- Description must be at most 350 characters (optional)
- Use the JavaScript function in the “Slug Generation” section above to preview the slug that will be generated
400 Bad Request: Missing required fields (e.g.,name), invalid name length (must be 1-100 characters), invalid description length (must be at most 350 characters), or invalid project slug401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project, or plan limit exceeded (e.g., maximum environments per project reached). See Pricing Plans API for details.404 Not Found: Project does not exist500 Internal Server Error: Failed to create environment
List Environments
Get all environments for a project. Endpoint:GET /api/projects/:projectSlug/environments
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the project
include_inactive(optional): Include inactive environments. Set to"true"to include soft-deleted environments. Default:false
Get Environment
Get details of a specific environment by slug. Endpoint:GET /api/projects/:projectSlug/environments/:environmentSlug
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the projectenvironmentSlug(required): The slug of the environment
400 Bad Request: Invalid project or environment slug401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project404 Not Found: Project or environment does not exist500 Internal Server Error: Failed to retrieve environment
Update Environment
Update an existing environment. Endpoint:PATCH /api/projects/:projectSlug/environments/:environmentSlug
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the projectenvironmentSlug(required): The slug of the environment to update
- The
isDefaultandisActivefields cannot be updated through this endpoint. Use theset-defaultendpoint to change the default environment, and these fields are managed automatically by the system. - Description must be at most 350 characters
400 Bad Request: Invalid slugs or no fields provided to update401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project404 Not Found: Project or environment does not exist500 Internal Server Error: Failed to update environment
Set Default Environment
Set an environment as the project’s default environment. Endpoint:PATCH /api/projects/:projectSlug/environments/:environmentSlug/set-default
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the projectenvironmentSlug(required): The slug of the environment to set as default
400 Bad Request: Invalid project or environment slug401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project404 Not Found: Project or environment does not exist500 Internal Server Error: Failed to set default environment
Delete Environment
Delete an environment (soft delete - marks environment as inactive). Endpoint:DELETE /api/projects/:projectSlug/environments/:environmentSlug
Authentication: Required
Path Parameters:
projectSlug(required): The slug of the projectenvironmentSlug(required): The slug of the environment to delete
400 Bad Request: Invalid project or environment slug401 Unauthorized: Missing or invalid authentication token403 Forbidden: You don’t own this project404 Not Found: Project or environment does not exist500 Internal Server Error: Failed to delete environment
Response Fields
Project Object
| Field | Type | Description |
|---|---|---|
id | number | Unique project ID |
userId | number | ID of the user who owns the project |
name | string | Project name |
slug | string | Unique project slug (globally unique) |
description | string | null | Project description |
isDefault | boolean | Whether this is the user’s default project |
isActive | boolean | Whether the project is active (false if soft-deleted) |
connectedCloudId | number | null | ID of the connected cloud connection |
createdAt | string | Timestamp when the project was created (ISO 8601) |
updatedAt | string | Timestamp when the project was last updated (ISO 8601) |
Environment Object
| Field | Type | Description |
|---|---|---|
id | number | Unique environment ID |
projectId | number | ID of the parent project |
name | string | Environment name |
slug | string | Unique environment slug (unique within project) |
description | string | null | Environment description |
isDefault | boolean | Whether this is the project’s default environment |
isActive | boolean | Whether the environment is active (false if soft-deleted) |
createdAt | string | Timestamp when the environment was created (ISO 8601) |
updatedAt | string | Timestamp when the environment was last updated (ISO 8601) |
Slug Generation
Project Slugs
- Slugs are automatically generated from the project name by:
- Converting to lowercase
- Replacing spaces with hyphens
- Removing special characters (keeping only alphanumeric and hyphens)
- Ensuring uniqueness (if slug exists, a number is appended)
- Custom slugs can be provided when creating or updating projects
- Project slugs must be globally unique across all users
Environment Slugs
- Slugs are automatically generated from the environment name using the same rules as project slugs
- Custom slugs can be provided when creating or updating environments
- Environment slugs must be unique within a project
Best Practices
- Naming: Use descriptive names for projects and environments (e.g.,
production,staging,development) - Slugs: Use consistent slug naming conventions for better URL readability
- Default Projects: Set a default project for quicker access to commonly used resources
- Default Environments: Set a default environment per project for easier navigation
- Organization: Group related resources by project and use environments to separate deployment stages