--- title: create-or-update-a-connector-project-connection product: vercel url: /docs/rest-api/sdk/connect/create-or-update-a-connector-project-connection canonical_url: "https://vercel.com/docs/rest-api/sdk/connect/create-or-update-a-connector-project-connection" last_updated: 2026-09-03 type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about create-or-update-a-connector-project-connection on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Create or update a connector project connection ```http POST /v1/connect/connectors/{connector}/projects/{projectId} ``` Connect a connector to a project, or replace the environments on an existing project connection. ## Authentication **bearerToken**: HTTP bearer ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `connector` | string | Yes | Stable connector ID or URL-encoded team-scoped UID. Examples: `scl_abc123` or `slack%2Fmy-bot`. | | `projectId` | string | Yes | Vercel project ID. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `teamId` | string | No | The team ID that scopes the request. Do not send it with slug. If both are omitted, Vercel uses the team associated with the token or the authenticated user's default team. The request returns 401 if no team can be selected. | | `slug` | string | No | The team slug that scopes the request. Do not send it with teamId. If both are omitted, Vercel uses the team associated with the token or the authenticated user's default team. The request returns 401 if no team can be selected. | ## Request body Required: Yes Content-Type: `application/json` ```json { "type": "object", "description": "Environments enabled for a connector project connection.", "required": [ "environments" ], "properties": { "environments": { "type": "array", "description": "One or more built-in environment names or stable custom environment IDs that belong to the project. Duplicate values are accepted and removed.", "items": { "description": "A built-in environment name or the stable env_* ID of a custom environment.", "anyOf": [ { "type": "string", "enum": [ "development", "preview", "production" ] }, { "type": "string", "pattern": "^env_" } ] } } } } ``` ## Example request ```typescript import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); async function run() { const result = await vercel.connect.upsertConnectorProjectConnection({ connector: "", projectId: "", teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l", slug: "my-team-url-slug", connectUpsertProjectConnectionRequest: { environments: [ "", ], }, }); console.log(result); } run(); ``` ## Example response ```json { "connectorId": "example_id", "project": { "id": "icfg_1234567890", "name": "Example Name", "customEnvironments": [ { "id": "icfg_1234567890", "slug": "string" } ] }, "enabledEnvironments": [], "createdAt": "123", "updatedAt": "123" } ``` ## Responses ### 200: The connector project connection was created or updated. Content-Type: `application/json` ```json { "type": "object", "description": "A connection between a connector and a Vercel project, including the environments where the connector is enabled.", "required": [ "connectorId", "createdAt", "enabledEnvironments", "project", "updatedAt" ], "properties": { "connectorId": { "type": "string", "description": "Stable `scl_` connector ID, even when the request used a UID." }, "project": { "type": "object", "description": "Vercel project connected to the connector.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Same Vercel project ID as the connection's top-level `projectId`." }, "name": { "type": "string", "description": "Current Vercel project name." }, "customEnvironments": { "type": "array", "description": "Custom environments available on the project. This list can include environments where the connector is not enabled.", "items": { "type": "object", "description": "Custom environments available on the project. This list can include environments where the connector is not enabled.", "required": [ "id", "slug" ] } } } }, "enabledEnvironments": { "type": "array", "description": "Environments where the connector is enabled for the project.", "items": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "development", "preview", "production" ] } ] } }, "createdAt": { "type": "number", "description": "Time when the project connection was created, in epoch milliseconds." }, "updatedAt": { "type": "number", "description": "Time when the project connection was last updated, in epoch milliseconds." } } } ``` ### 400: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 401: The request is not authorized. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 403: You do not have permission to access this resource. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 404: The requested resource was not found. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 410: The requested resource is no longer available. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` --- ## Related - [connect endpoints](/docs/rest-api#connect) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)