{ "openapi": "3.0.3", "info": { "title": "Vercel API", "description": "Vercel combines the best developer experience with an obsessive focus on end-user performance. Our platform enables frontend teams to do their best work.", "contact": { "email": "support@vercel.com", "name": "Vercel Support", "url": "https://vercel.com/support" }, "version": "0.0.1" }, "servers": [ { "url": "https://api.vercel.com", "description": "Production API" } ], "paths": { "/v1/installations/{integrationConfigurationId}": { "patch": { "description": "This endpoint updates an integration installation.", "operationId": "update-installation", "security": [ { "bearerToken": [] } ], "summary": "Update Installation", "tags": [ "marketplace" ], "responses": { "204": { "description": "" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "pending", "onboarding", "suspended", "resumed", "uninstalled", "error" ] }, "externalId": { "type": "string" }, "billingPlan": { "type": "object", "required": [ "id", "type", "name" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "prepayment", "subscription" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "paymentMethodRequired": { "type": "boolean" }, "cost": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false } }, "highlightedDetails": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false } }, "effectiveDate": { "type": "string" } }, "additionalProperties": true }, "notification": { "oneOf": [ { "type": "object", "required": [ "level", "title" ], "properties": { "level": { "type": "string", "enum": [ "info", "warn", "error" ] }, "title": { "type": "string" }, "message": { "type": "string" }, "href": { "type": "string", "format": "uri", "pattern": "^https?://|^sso:" } } }, { "type": "null" } ], "description": "A notification to display to your customer. Send `null` to clear the current notification." } }, "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/account": { "get": { "description": "Fetches the best account or user’s contact info", "operationId": "get-account-info", "security": [ { "bearerToken": [] } ], "summary": "Get Account Information", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "contact": { "nullable": true, "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "email" ], "type": "object", "description": "The best contact for the integration, which can change as team members and their roles change." }, "name": { "type": "string", "description": "The name of the team the installation is tied to." }, "url": { "type": "string", "description": "A URL linking to the installation in the Vercel Dashboard." } }, "required": [ "contact", "url" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/installations/{integrationConfigurationId}/member/{memberId}": { "get": { "description": "Returns the member role and other information for a given member ID (\"user_id\" claim in the SSO OIDC token).", "operationId": "get-member", "security": [ { "bearerToken": [] } ], "summary": "Get Member Information", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "globalUserId": { "type": "string" }, "id": { "type": "string" }, "role": { "type": "string", "enum": [ "ADMIN", "USER" ], "description": "\"The `ADMIN` role, by default, is provided to users capable of installing integrations, while the `USER` role can be granted to Vercel users with the Vercel `Billing` or Vercel `Viewer` role, which are considered to be Read-Only roles.\"" }, "userEmail": { "type": "string" } }, "required": [ "id", "role" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/installations/{integrationConfigurationId}/credentials/rotate": { "post": { "description": "Issues a replacement access token for an installation, so a partner can rotate a credential it believes is compromised without the customer having to reinstall. Authenticated by the credential being replaced plus the integration's client secret: a leaked access token on its own cannot rotate itself, which would otherwise let an attacker take over the installation and lock the partner out. The previous credential intentionally stays valid so in-flight requests keep working. Retiring it is a separate, explicit operation — a partner is never left mid-rotation without a working credential.", "operationId": "rotate-installation-credential", "security": [ { "bearerToken": [] } ], "summary": "Rotate Installation Credential", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "number" }, "scope": { "type": "string" }, "token_type": { "type": "string", "enum": [ "oauth2-token" ] } }, "required": [ "access_token", "expires_in", "scope", "token_type" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "client_secret" ], "properties": { "client_secret": { "type": "string", "maxLength": 512 }, "client_id": { "type": "string" } }, "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/credentials/revoke": { "post": { "description": "Retires a superseded installation credential, so a partner can complete a rotation it started with `POST /credentials/rotate` — the leaked credential stops working without the customer having to reinstall. Authenticated by a live installation credential plus the integration's client secret. The credential to retire is named in the body rather than being the one that authenticates, so the ordinary flow is: rotate, store the replacement, then authenticate with the replacement and revoke the old one. Refuses to retire an installation's last live credential. Rotation exists so remediation is not customer-visible; revoking the only credential would undo that and leave the install needing a reinstall.", "operationId": "revoke-installation-credential", "security": [ { "bearerToken": [] } ], "summary": "Revoke Installation Credential", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "already_revoked": { "type": "boolean", "enum": [ false, true ] }, "revoked": { "type": "boolean", "enum": [ false, true ] } }, "required": [ "already_revoked", "revoked" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "client_secret" ], "properties": { "token": { "type": "string", "maxLength": 512 }, "client_secret": { "type": "string", "maxLength": 512 }, "client_id": { "type": "string" } }, "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/events": { "post": { "description": "Partner notifies Vercel of any changes made to an Installation or a Resource. Vercel is expected to use `list-resources` and other read APIs to get the new state.

`resource.updated` event should be dispatched when any state of a resource linked to Vercel is modified by the partner.
`installation.updated` event should be dispatched when an installation's billing plan is changed via the provider instead of Vercel.

Resource update use cases:

- The user renames a database in the partner’s application. The partner should dispatch a `resource.updated` event to notify Vercel to update the resource in Vercel’s datastores.
- A resource has been suspended due to a lack of use. The partner should dispatch a `resource.updated` event to notify Vercel to update the resource's status in Vercel's datastores.
", "operationId": "create-event", "security": [ { "bearerToken": [] } ], "summary": "Create Event", "tags": [ "marketplace" ], "responses": { "201": { "description": "" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "event" ], "properties": { "event": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "installation.updated" ] }, "billingPlanId": { "type": "string", "description": "The installation-level billing plan ID" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "resource.updated" ] }, "productId": { "type": "string", "description": "Partner-provided product slug or id" }, "resourceId": { "type": "string", "description": "Partner provided resource ID" } }, "required": [ "type", "resourceId" ], "additionalProperties": false } ] } }, "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/resources": { "get": { "description": "Get all resources for a given installation ID.", "operationId": "get-integration-resources", "security": [ { "bearerToken": [] } ], "summary": "Get Integration Resources", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "resources": { "items": { "properties": { "billingPlanId": { "type": "string", "description": "The ID of the billing plan the resource is subscribed to, if applicable" }, "internalId": { "type": "string", "description": "The ID assigned by Vercel for the given resource" }, "metadata": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "items": { "type": "string" }, "type": "array", "description": "The configured metadata for the resource as defined by its product's Metadata Schema" }, { "items": { "type": "number" }, "type": "array", "description": "The configured metadata for the resource as defined by its product's Metadata Schema" }, { "type": "boolean", "enum": [ false, true ] } ] }, "type": "object", "description": "The configured metadata for the resource as defined by its product's Metadata Schema" }, "name": { "type": "string", "description": "The name of the resource as it is recorded in Vercel" }, "notification": { "properties": { "href": { "type": "string" }, "level": { "type": "string", "enum": [ "error", "info", "warn" ] }, "message": { "type": "string" }, "title": { "type": "string" } }, "required": [ "level", "title" ], "type": "object", "description": "The notification, if set, displayed to the user when viewing the resource in Vercel" }, "partnerId": { "type": "string", "description": "The ID provided by the partner for the given resource" }, "productId": { "type": "string", "description": "The ID of the product the resource is derived from" }, "protocolSettings": { "properties": { "authentication": { "properties": { "appUrls": { "items": { "properties": { "target": { "type": "string", "enum": [ "development", "preview", "production" ] }, "url": { "type": "string" } }, "required": [ "target", "url" ], "type": "object" }, "type": "array" } }, "type": "object" }, "experimentation": { "properties": { "edgeConfigId": { "type": "string" }, "edgeConfigSyncingEnabled": { "type": "boolean", "enum": [ false, true ] }, "edgeConfigTokenId": { "type": "string" }, "globalConfigId": { "type": "string" }, "globalConfigSyncingEnabled": { "type": "boolean", "enum": [ false, true ] } }, "type": "object" } }, "type": "object", "description": "Any settings provided for the resource to support its product's protocols" }, "status": { "type": "string", "enum": [ "error", "onboarding", "pending", "ready", "resumed", "suspended", "uninstalled" ], "description": "The current status of the resource" } }, "required": [ "internalId", "name", "partnerId", "productId" ], "type": "object" }, "type": "array" } }, "required": [ "resources" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/installations/{integrationConfigurationId}/resources/{resourceId}": { "get": { "description": "Get a resource by its partner ID.", "operationId": "get-integration-resource", "security": [ { "bearerToken": [] } ], "summary": "Get Integration Resource", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "billingPlanId": { "type": "string", "description": "The ID of the billing plan the resource is subscribed to, if applicable" }, "id": { "type": "string", "description": "The ID provided by the 3rd party provider for the given resource" }, "internalId": { "type": "string", "description": "The ID assigned by Vercel for the given resource" }, "metadata": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "items": { "type": "string" }, "type": "array", "description": "The configured metadata for the resource as defined by its product's Metadata Schema" }, { "items": { "type": "number" }, "type": "array", "description": "The configured metadata for the resource as defined by its product's Metadata Schema" }, { "type": "boolean", "enum": [ false, true ] } ] }, "type": "object", "description": "The configured metadata for the resource as defined by its product's Metadata Schema" }, "name": { "type": "string", "description": "The name of the resource as it is recorded in Vercel" }, "notification": { "properties": { "href": { "type": "string" }, "level": { "type": "string", "enum": [ "error", "info", "warn" ] }, "message": { "type": "string" }, "title": { "type": "string" } }, "required": [ "level", "title" ], "type": "object", "description": "The notification, if set, displayed to the user when viewing the resource in Vercel" }, "productId": { "type": "string", "description": "The ID of the product the resource is derived from" }, "protocolSettings": { "properties": { "authentication": { "properties": { "appUrls": { "items": { "properties": { "target": { "type": "string", "enum": [ "development", "preview", "production" ] }, "url": { "type": "string" } }, "required": [ "target", "url" ], "type": "object" }, "type": "array" } }, "type": "object" }, "experimentation": { "properties": { "edgeConfigId": { "type": "string" }, "globalConfigId": { "type": "string" } }, "type": "object" } }, "type": "object", "description": "Any settings provided for the resource to support its product's protocols" }, "status": { "type": "string", "enum": [ "error", "onboarding", "pending", "ready", "resumed", "suspended", "uninstalled" ], "description": "The current status of the resource" } }, "required": [ "id", "internalId", "name", "productId" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "description": "The ID of the integration configuration (installation) the resource belongs to", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the integration configuration (installation) the resource belongs to" } }, { "name": "resourceId", "description": "The ID provided by the 3rd party provider for the given resource", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID provided by the 3rd party provider for the given resource" } } ] }, "delete": { "description": "Delete a resource owned by the selected installation ID.", "operationId": "delete-integration-resource", "security": [ { "bearerToken": [] } ], "summary": "Delete Integration Resource", "tags": [ "marketplace" ], "responses": { "204": { "description": "" }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "describe": "The external provider's ID of the resource to delete" } } ] }, "put": { "description": "This endpoint imports (upserts) a resource to Vercel's installation. This may be needed if resources can be independently created on the partner's side and need to be synchronized to Vercel. When importing as part of the user-initiated import flow, call this endpoint before redirecting the user back to Vercel. See the [Import existing resources flow](https://vercel.com/docs/integrations/create-integration/marketplace-flows#import-existing-resources-flow) for the full contract.", "operationId": "import-resource", "security": [ { "bearerToken": [] } ], "summary": "Import Resource", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" }, "422": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "productId", "name", "status" ], "properties": { "ownership": { "type": "string", "enum": [ "owned", "linked", "sandbox" ] }, "productId": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "pending", "onboarding", "suspended", "resumed", "uninstalled", "error" ] }, "metadata": { "type": "object", "additionalProperties": true }, "billingPlan": { "type": "object", "required": [ "id", "type", "name" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "prepayment", "subscription" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "paymentMethodRequired": { "type": "boolean" }, "cost": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false } }, "highlightedDetails": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false } }, "effectiveDate": { "type": "string" } }, "additionalProperties": true }, "notification": { "type": "object", "required": [ "level", "title" ], "properties": { "level": { "type": "string", "enum": [ "info", "warn", "error" ] }, "title": { "type": "string" }, "message": { "type": "string" }, "href": { "type": "string", "format": "uri", "pattern": "^https?://|^sso:" } } }, "extras": { "type": "object", "additionalProperties": true }, "secrets": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "prefix": { "type": "string" }, "environmentOverrides": { "type": "object", "description": "A map of environments to override values for the secret, used for setting different values across deployments in production, preview, and development environments. Note: the same value will be used for all deployments in the given environment.", "properties": { "development": { "type": "string", "description": "Value used for development environment." }, "preview": { "type": "string", "description": "Value used for preview environment." }, "production": { "type": "string", "description": "Value used for production environment." } } } }, "additionalProperties": false } } }, "additionalProperties": false } } } } }, "patch": { "description": "This endpoint updates an existing resource in the installation. All parameters are optional, allowing partial updates.", "operationId": "update-resource", "security": [ { "bearerToken": [] } ], "summary": "Update Resource", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" }, "422": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ownership": { "type": "string", "enum": [ "owned", "linked", "sandbox" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "pending", "onboarding", "suspended", "resumed", "uninstalled", "error" ] }, "metadata": { "type": "object", "additionalProperties": true }, "billingPlan": { "type": "object", "required": [ "id", "type", "name" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "prepayment", "subscription" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "paymentMethodRequired": { "type": "boolean" }, "cost": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false } }, "highlightedDetails": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false } }, "effectiveDate": { "type": "string" } }, "additionalProperties": true }, "notification": { "oneOf": [ { "type": "object", "required": [ "level", "title" ], "properties": { "level": { "type": "string", "enum": [ "info", "warn", "error" ] }, "title": { "type": "string" }, "message": { "type": "string" }, "href": { "type": "string", "format": "uri", "pattern": "^https?://|^sso:" } } }, { "type": "null" } ] }, "extras": { "type": "object", "additionalProperties": true }, "secrets": { "oneOf": [ { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "prefix": { "type": "string" }, "environmentOverrides": { "type": "object", "description": "A map of environments to override values for the secret, used for setting different values across deployments in production, preview, and development environments. Note: the same value will be used for all deployments in the given environment.", "properties": { "development": { "type": "string", "description": "Value used for development environment." }, "preview": { "type": "string", "description": "Value used for preview environment." }, "production": { "type": "string", "description": "Value used for production environment." } } } }, "additionalProperties": false } }, { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "prefix": { "type": "string" }, "environmentOverrides": { "type": "object", "description": "A map of environments to override values for the secret, used for setting different values across deployments in production, preview, and development environments. Note: the same value will be used for all deployments in the given environment.", "properties": { "development": { "type": "string", "description": "Value used for development environment." }, "preview": { "type": "string", "description": "Value used for preview environment." }, "production": { "type": "string", "description": "Value used for production environment." } } } }, "additionalProperties": false } }, "partial": { "type": "boolean", "description": "If true, will only overwrite the provided secrets instead of replacing all secrets." } }, "additionalProperties": false } ] } }, "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/billing": { "post": { "description": "Sends the billing and usage data. The partner should do this at least once a day and ideally once per hour.
Use the `credentials.access_token` we provided in the [Upsert Installation](#upsert-installation) body to authorize this request.", "operationId": "submit-billing-data", "security": [ { "bearerToken": [] } ], "summary": "Submit Billing Data", "tags": [ "marketplace" ], "responses": { "201": { "description": "" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Server time of your integration, used to determine the most recent data for race conditions & updates. Only the latest usage data for a given day, week, and month will be kept." }, "eod": { "type": "string", "format": "date-time", "description": "End of Day, the UTC datetime for when the end of the billing/usage day is in UTC time. This tells us which day the usage data is for, and also allows for your \"end of day\" to be different from UTC 00:00:00. eod must be within the period dates, and cannot be older than 24h earlier from our server's current time." }, "period": { "type": "object", "description": "Period for the billing cycle. The period end date cannot be older than 24 hours earlier than our current server's time.", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } }, "required": [ "start", "end" ], "additionalProperties": false }, "billing": { "description": "Billing data (interim invoicing data).", "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "billingPlanId": { "type": "string", "description": "Partner's billing plan ID." }, "resourceId": { "type": "string", "description": "Partner's resource ID." }, "start": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "end": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "name": { "type": "string", "description": "Line item name." }, "details": { "type": "string", "description": "Line item details." }, "price": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Price per unit." }, "quantity": { "type": "number", "description": "Quantity of units." }, "units": { "type": "string", "description": "Units of the quantity." }, "total": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Total amount." } }, "required": [ "billingPlanId", "name", "price", "quantity", "units", "total" ], "additionalProperties": false } }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "billingPlanId": { "type": "string", "description": "Partner's billing plan ID." }, "resourceId": { "type": "string", "description": "Partner's resource ID." }, "start": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "end": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "name": { "type": "string", "description": "Line item name." }, "details": { "type": "string", "description": "Line item details." }, "price": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Price per unit." }, "quantity": { "type": "number", "description": "Quantity of units." }, "units": { "type": "string", "description": "Units of the quantity." }, "total": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Total amount." } }, "required": [ "billingPlanId", "name", "price", "quantity", "units", "total" ], "additionalProperties": false } }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "billingPlanId": { "type": "string", "description": "Partner's billing plan ID." }, "resourceId": { "type": "string", "description": "Partner's resource ID." }, "start": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "end": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "name": { "type": "string", "description": "Discount name." }, "details": { "type": "string", "description": "Discount details." }, "amount": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Discount amount." } }, "required": [ "billingPlanId", "name", "amount" ], "additionalProperties": false } } }, "required": [ "items" ] } ] }, "usage": { "type": "array", "items": { "type": "object", "properties": { "resourceId": { "type": "string", "description": "Partner's resource ID." }, "name": { "type": "string", "description": "Metric name." }, "type": { "type": "string", "description": "\n Type of the metric.\n - total: measured total value, such as Database size\n - interval: usage during the period, such as i/o or number of queries.\n - rate: rate of usage, such as queries per second.\n ", "enum": [ "total", "interval", "rate" ] }, "units": { "type": "string", "description": "Metric units. Example: \"GB\"" }, "dayValue": { "type": "number", "description": "Metric value for the day. Could be a final or an interim value for the day." }, "periodValue": { "type": "number", "description": "Metric value for the billing period. Could be a final or an interim value for the period." }, "planValue": { "type": "number", "description": "The limit value of the metric for a billing period, if a limit is defined by the plan." } }, "required": [ "name", "type", "units", "dayValue", "periodValue" ], "additionalProperties": false } } }, "required": [ "timestamp", "eod", "period", "billing", "usage" ], "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/billing/invoices": { "post": { "description": "This endpoint allows the partner to submit an invoice to Vercel. The invoice is created in Vercel's billing system and sent to the customer. Depending on the type of billing plan, the invoice can be sent at a time of signup, at the start of the billing period, or at the end of the billing period.

Use the `credentials.access_token` we provided in the [Upsert Installation](#upsert-installation) body to authorize this request.
There are several limitations to the invoice submission:

1. A resource can only be billed once per the billing period and the billing plan.
2. The billing plan used to bill the resource must have been active for this resource during the billing period.
3. The billing plan used must be a subscription plan.
4. The interim usage data must be sent hourly for all types of subscriptions. See [Send subscription billing and usage data](#send-subscription-billing-and-usage-data) API on how to send interim billing and usage data.
5. If provided, `externalId` must be unique for the installation.
", "operationId": "submit-invoice", "security": [ { "bearerToken": [] } ], "summary": "Submit Invoice", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "invoiceId": { "type": "string" }, "test": { "type": "boolean", "enum": [ false, true ] }, "validationErrors": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } } }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "description": "Partner-provided invoice identifier. If provided, it must be unique for this installation." }, "invoiceDate": { "type": "string", "format": "date-time", "description": "Invoice date. Must be within the period's start and end." }, "memo": { "type": "string", "description": "Additional memo for the invoice." }, "period": { "type": "object", "description": "Subscription period for this billing cycle.", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } }, "required": [ "start", "end" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "resourceId": { "type": "string", "description": "Partner's resource ID." }, "billingPlanId": { "type": "string", "description": "Partner's billing plan ID." }, "start": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "end": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "name": { "type": "string" }, "details": { "type": "string" }, "price": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Currency amount as a decimal string." }, "quantity": { "type": "number" }, "units": { "type": "string" }, "total": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Currency amount as a decimal string." } }, "required": [ "billingPlanId", "name", "price", "quantity", "units", "total" ], "additionalProperties": false } }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "resourceId": { "type": "string", "description": "Partner's resource ID." }, "billingPlanId": { "type": "string", "description": "Partner's billing plan ID." }, "start": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "end": { "type": "string", "format": "date-time", "description": "Start and end are only needed if different from the period's start/end." }, "name": { "type": "string" }, "details": { "type": "string" }, "amount": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Currency amount as a decimal string." } }, "required": [ "billingPlanId", "name", "amount" ], "additionalProperties": false } }, "final": { "type": "boolean", "description": "Set this to `true` if this is the final invoice for the installation. Can only be set when the installation is pending deletion." }, "test": { "type": "object", "description": "Test mode", "properties": { "validate": { "type": "boolean" }, "result": { "type": "string", "enum": [ "paid", "notpaid", "overdue" ] } }, "additionalProperties": false } }, "required": [ "invoiceDate", "period", "items" ], "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/billing/finalize": { "post": { "description": "This endpoint allows the partner to mark an installation as finalized. This means you will not send any more invoices for the installation. Use this after a customer has requested uninstall and you have sent any remaining invoices. This will allow the uninstall process to proceed immediately after all invoices have been paid.
Use the `credentials.access_token` we provided in the [Upsert Installation](#upsert-installation) body to authorize this request.", "operationId": "finalize-installation", "security": [ { "bearerToken": [] } ], "summary": "Finalize Installation", "tags": [ "marketplace" ], "responses": { "204": { "description": "" }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/installations/{integrationConfigurationId}/billing/invoices/{invoiceId}": { "get": { "description": "Get Invoice details and status for a given invoice ID.

See [Billing Events with Webhooks documentation](https://vercel.com/docs/integrations/create-integration/marketplace-api#working-with-billing-events-through-webhooks) on how to receive invoice events. This endpoint is used to retrieve the invoice details.", "operationId": "get-invoice", "security": [ { "bearerToken": [] } ], "summary": "Get Invoice", "tags": [ "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "created": { "type": "string", "description": "System creation date. ISO 8601 timestamp." }, "discounts": { "items": { "properties": { "amount": { "type": "string", "description": "Discount amount. A dollar-based decimal string." }, "billingPlanId": { "type": "string", "description": "Partner's billing plan ID." }, "details": { "type": "string", "description": "Additional discount details." }, "end": { "type": "string", "description": "Start and end are only needed if different from the period's start/end. ISO 8601 timestamp." }, "name": { "type": "string", "description": "Discount name." }, "resourceId": { "type": "string", "description": "Partner's resource ID. If not specified, indicates installation-wide discount." }, "start": { "type": "string", "description": "Start and end are only needed if different from the period's start/end. ISO 8601 timestamp." } }, "required": [ "amount", "billingPlanId", "name" ], "type": "object", "description": "Invoice discounts." }, "type": "array", "description": "Invoice discounts." }, "externalId": { "type": "string", "description": "Partner-supplied Invoice ID, if applicable." }, "invoiceDate": { "type": "string", "description": "Invoice date. ISO 8601 timestamp." }, "invoiceId": { "type": "string", "description": "Vercel Marketplace Invoice ID." }, "invoiceNumber": { "type": "string", "description": "User-readable invoice number." }, "items": { "items": { "properties": { "billingPlanId": { "type": "string", "description": "Partner's billing plan ID." }, "details": { "type": "string", "description": "Additional item details." }, "end": { "type": "string", "description": "Start and end are only needed if different from the period's start/end. ISO 8601 timestamp." }, "name": { "type": "string", "description": "Invoice item name." }, "price": { "type": "string", "description": "Item price. A dollar-based decimal string." }, "quantity": { "type": "number", "description": "Item quantity." }, "resourceId": { "type": "string", "description": "Partner's resource ID. If not specified, indicates installation-wide item." }, "start": { "type": "string", "description": "Start and end are only needed if different from the period's start/end. ISO 8601 timestamp." }, "total": { "type": "string", "description": "Item total. A dollar-based decimal string." }, "units": { "type": "string", "description": "Units for item's quantity." } }, "required": [ "billingPlanId", "name", "price", "quantity", "total", "units" ], "type": "object", "description": "Invoice items." }, "type": "array", "description": "Invoice items." }, "memo": { "type": "string", "description": "Additional memo for the invoice." }, "paidAt": { "type": "string", "description": "Moment the invoice was paid. ISO 8601 timestamp." }, "period": { "properties": { "end": { "type": "string" }, "start": { "type": "string" } }, "required": [ "end", "start" ], "type": "object", "description": "Subscription period for this billing cycle. ISO 8601 timestamps." }, "refundedAt": { "type": "string", "description": "Most recent moment the invoice was refunded. ISO 8601 timestamp." }, "refundReason": { "type": "string", "description": "The reason for refund. Only applicable for states \"refunded\" or \"refund_request\"." }, "refundTotal": { "type": "string", "description": "Refund amount. Only applicable for states \"refunded\" or \"refund_request\". A dollar-based decimal string." }, "state": { "type": "string", "enum": [ "draft", "invoiced", "notpaid", "overdue", "paid", "pending", "refund_requested", "refunded", "scheduled" ], "description": "Invoice state." }, "test": { "type": "boolean", "enum": [ false, true ], "description": "Whether the invoice is in the testmode (no real transaction created)." }, "total": { "type": "string", "description": "Invoice total amount. A dollar-based decimal string." }, "updated": { "type": "string", "description": "System update date. ISO 8601 timestamp." } }, "required": [ "created", "invoiceDate", "invoiceId", "items", "period", "state", "total", "updated" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" }, "429": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/installations/{integrationConfigurationId}/billing/invoices/{invoiceId}/actions": { "post": { "description": "This endpoint allows the partner to request a refund for an invoice to Vercel. The invoice is created using the [Submit Invoice API](#submit-invoice-api).", "operationId": "update-invoice", "security": [ { "bearerToken": [] } ], "summary": "Invoice Actions", "tags": [ "marketplace" ], "responses": { "204": { "description": "" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "refund" ] }, "reason": { "type": "string", "description": "Refund reason." }, "total": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "The total amount to be refunded. Must be less than or equal to the total amount of the invoice." } }, "required": [ "action", "reason", "total" ], "additionalProperties": false } ] } } } } } }, "/v1/installations/{integrationConfigurationId}/billing/balance": { "post": { "description": "Sends the prepayment balances. The partner should do this at least once a day and ideally once per hour.
Use the `credentials.access_token` we provided in the [Upsert Installation](#upsert-installation) body to authorize this request.", "operationId": "submit-prepayment-balances", "security": [ { "bearerToken": [] } ], "summary": "Submit Prepayment Balances", "tags": [ "marketplace" ], "responses": { "201": { "description": "" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Server time of your integration, used to determine the most recent data for race conditions & updates. Only the latest usage data for a given day, week, and month will be kept." }, "balances": { "type": "array", "items": { "type": "object", "description": "A credit balance for a particular token type", "properties": { "resourceId": { "type": "string", "description": "Partner's resource ID, exclude if credits are tied to the installation and not an individual resource." }, "credit": { "type": "string", "description": "A human-readable description of the credits the user currently has, e.g. \"2,000 Tokens\"" }, "nameLabel": { "type": "string", "description": "The name of the credits, for display purposes, e.g. \"Tokens\"" }, "currencyValueInCents": { "type": "number", "description": "The dollar value of the credit balance, in USD and provided in cents, which is used to trigger automatic purchase thresholds." } }, "required": [ "currencyValueInCents" ], "additionalProperties": false } } }, "required": [ "timestamp", "balances" ], "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/products/{integrationProductIdOrSlug}/resources/{resourceId}/secrets": { "put": { "description": "This endpoint is deprecated and replaced with the endpoint [Update Resource Secrets](#update-resource-secrets).
This endpoint updates the secrets of a resource. If a resource has projects connected, the connected secrets are updated with the new secrets. The old secrets may still be used by existing connected projects because they are not automatically redeployed. Redeployment is a manual action and must be completed by the user. All new project connections will use the new secrets.

Use cases for this endpoint:

- Resetting the credentials of a database in the partner. If the user requests the credentials to be updated in the partner’s application, the partner post the new set of secrets to Vercel, the user should redeploy their application and the expire the old credentials.
", "operationId": "update-resource-secrets", "security": [ { "bearerToken": [] } ], "summary": "Deprecated: true. Update Resource Secrets (Deprecated)", "tags": [ "marketplace" ], "deprecated": true, "responses": { "201": { "description": "" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" }, "422": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "integrationProductIdOrSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "prefix": { "type": "string" }, "environmentOverrides": { "type": "object", "description": "A map of environments to override values for the secret, used for setting different values across deployments in production, preview, and development environments. Note: the same value will be used for all deployments in the given environment.", "properties": { "development": { "type": "string", "description": "Value used for development environment." }, "preview": { "type": "string", "description": "Value used for preview environment." }, "production": { "type": "string", "description": "Value used for production environment." } } } }, "additionalProperties": false } }, "partial": { "type": "boolean", "description": "If true, will only update the provided secrets" } }, "additionalProperties": false } } } } } }, "/v1/installations/{integrationConfigurationId}/resources/{resourceId}/secrets": { "put": { "description": "This endpoint updates the secrets of a resource. If a resource has projects connected, the connected secrets are updated with the new secrets. The old secrets may still be used by existing connected projects because they are not automatically redeployed. Redeployment is a manual action and must be completed by the user. All new project connections will use the new secrets.

Use cases for this endpoint:

- Resetting the credentials of a database in the partner. If the user requests the credentials to be updated in the partner’s application, the partner post the new set of secrets to Vercel, the user should redeploy their application and the expire the old credentials.
", "operationId": "update-resource-secrets-by-id", "security": [ { "bearerToken": [] } ], "summary": "Update Resource Secrets", "tags": [ "marketplace" ], "responses": { "201": { "description": "" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" }, "422": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "prefix": { "type": "string" }, "environmentOverrides": { "type": "object", "description": "A map of environments to override values for the secret, used for setting different values across deployments in production, preview, and development environments. Note: the same value will be used for all deployments in the given environment.", "properties": { "development": { "type": "string", "description": "Value used for development environment." }, "preview": { "type": "string", "description": "Value used for preview environment." }, "production": { "type": "string", "description": "Value used for production environment." } } } }, "additionalProperties": false } }, "partial": { "type": "boolean", "description": "If true, will only overwrite the provided secrets instead of replacing all secrets." } }, "additionalProperties": false } } } } } }, "/v1/integrations/sso/token": { "post": { "description": "During the autorization process, Vercel sends the user to the provider [redirectLoginUrl](https://vercel.com/docs/integrations/create-integration/submit-integration#redirect-login-url), that includes the OAuth authorization `code` parameter. The provider then calls the SSO Token Exchange endpoint with the sent code and receives the OIDC token. They log the user in based on this token and redirects the user back to the Vercel account using deep-link parameters included the redirectLoginUrl. Providers should not persist the returned `id_token` in a database since the token will expire. See [**Authentication with SSO**](https://vercel.com/docs/integrations/create-integration/marketplace-api#authentication-with-sso) for more details.", "operationId": "exchange-sso-token", "security": [], "summary": "SSO Token Exchange", "tags": [ "authentication", "marketplace" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "access_token": { "nullable": true, "type": "string" }, "expires_in": { "type": "number" }, "id_token": { "type": "string" }, "refresh_token": { "type": "string" }, "token_type": { "nullable": true, "type": "string" } }, "required": [ "access_token", "id_token", "token_type" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "number" }, "id_token": { "type": "string" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } }, "required": [ "access_token", "expires_in", "id_token", "refresh_token", "token_type" ], "type": "object" } ] } } } }, "400": { "description": "One of the provided values in the request body is invalid." }, "403": { "description": "" }, "500": { "description": "" } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "client_id", "client_secret", "grant_type" ], "properties": { "code": { "type": "string", "description": "The sensitive code received from Vercel" }, "state": { "type": "string", "description": "The state received from the initialization request" }, "client_id": { "type": "string", "description": "The integration client id" }, "client_secret": { "type": "string", "description": "The integration client secret" }, "redirect_uri": { "type": "string", "description": "The integration redirect URI" }, "grant_type": { "type": "string", "description": "The grant type, when using x-www-form-urlencoded content type", "enum": [ "authorization_code" ] } } }, { "type": "object", "required": [ "refresh_token", "client_id", "client_secret", "grant_type" ], "properties": { "refresh_token": { "type": "string", "description": "The refresh token received from previous token exchange" }, "client_id": { "type": "string", "description": "The integration client id" }, "client_secret": { "type": "string", "description": "The integration client secret" }, "grant_type": { "type": "string", "description": "The grant type, when using x-www-form-urlencoded content type", "enum": [ "refresh_token" ] } } } ] } } } } } }, "/v1/installations/{integrationConfigurationId}/resources/{resourceId}/experimentation/items": { "post": { "description": "Create one or multiple experimentation items", "operationId": "createInstallationsByIntegrationConfigurationIdResourcesByResourceIdExperimentationItems", "security": [ { "bearerToken": [] } ], "summary": "Create one or multiple experimentation items", "tags": [ "marketplace" ], "responses": { "204": { "description": "The items were created" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "origin" ], "properties": { "id": { "type": "string", "maxLength": 1024 }, "slug": { "type": "string", "maxLength": 1024 }, "origin": { "type": "string", "maxLength": 2048 }, "category": { "type": "string", "enum": [ "experiment", "flag" ] }, "name": { "type": "string", "maxLength": 1024 }, "description": { "type": "string", "maxLength": 1024 }, "isArchived": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } } } } } } } } } } }, "/v1/installations/{integrationConfigurationId}/resources/{resourceId}/experimentation/items/{itemId}": { "patch": { "description": "Patch an existing experimentation item", "operationId": "updateInstallationsByIntegrationConfigurationIdResourcesByResourceIdExperimentationItemsByItemId", "security": [ { "bearerToken": [] } ], "summary": "Patch an existing experimentation item", "tags": [ "marketplace" ], "responses": { "204": { "description": "The item was updated" }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "slug", "origin" ], "properties": { "slug": { "type": "string", "maxLength": 1024 }, "origin": { "type": "string", "maxLength": 2048 }, "name": { "type": "string", "maxLength": 1024 }, "category": { "type": "string", "enum": [ "experiment", "flag" ] }, "description": { "type": "string", "maxLength": 1024 }, "isArchived": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } } } } } } }, "delete": { "description": "Delete an existing experimentation item", "operationId": "deleteInstallationsByIntegrationConfigurationIdResourcesByResourceIdExperimentationItemsByItemId", "security": [ { "bearerToken": [] } ], "summary": "Delete an existing experimentation item", "tags": [ "marketplace" ], "responses": { "204": { "description": "The item was deleted" }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/installations/{integrationConfigurationId}/resources/{resourceId}/experimentation/global-config": { "head": { "description": "When the user enabled Global Config syncing, then this endpoint can be used by the partner to fetch the contents of the Global Config.", "operationId": "headInstallationsByIntegrationConfigurationIdResourcesByResourceIdExperimentationGlobalConfig", "security": [ { "bearerToken": [] } ], "summary": "Get the data of a user-provided Global Config", "tags": [ "marketplace" ], "responses": { "200": { "description": "The Global Config data", "content": { "application/json": { "schema": { "properties": { "digest": { "type": "string" }, "items": { "additionalProperties": { "$ref": "#/components/schemas/GlobalConfigItemValue" }, "type": "object" }, "purpose": { "type": "string", "enum": [ "experimentation", "flags" ] }, "updatedAt": { "type": "number" } }, "required": [ "digest", "items", "updatedAt" ], "type": "object" } } } }, "304": { "description": "" }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "description": "When the user enabled Global Config syncing, then this endpoint can be used by the partner to fetch the contents of the Global Config.", "operationId": "getInstallationsByIntegrationConfigurationIdResourcesByResourceIdExperimentationGlobalConfig", "security": [ { "bearerToken": [] } ], "summary": "Get the data of a user-provided Global Config", "tags": [ "marketplace" ], "responses": { "200": { "description": "The Global Config data", "content": { "application/json": { "schema": { "properties": { "digest": { "type": "string" }, "items": { "additionalProperties": { "$ref": "#/components/schemas/GlobalConfigItemValue" }, "type": "object" }, "purpose": { "type": "string", "enum": [ "experimentation", "flags" ] }, "updatedAt": { "type": "number" } }, "required": [ "digest", "items", "updatedAt" ], "type": "object" } } } }, "304": { "description": "" }, "400": { "description": "One of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "410": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "description": "When the user enabled Global Config syncing, then this endpoint can be used by the partner to push their configuration data into the relevant Global Config.", "operationId": "replaceInstallationsByIntegrationConfigurationIdResourcesByResourceIdExperimentationGlobalConfig", "security": [ { "bearerToken": [] } ], "summary": "Push data into a user-provided Global Config", "tags": [ "marketplace" ], "responses": { "200": { "description": "The Global Config was updated", "content": { "application/json": { "schema": { "properties": { "digest": { "type": "string" }, "items": { "additionalProperties": { "$ref": "#/components/schemas/GlobalConfigItemValue" }, "type": "object" }, "purpose": { "type": "string", "enum": [ "experimentation", "flags" ] }, "updatedAt": { "type": "number" } }, "required": [ "digest", "items", "updatedAt" ], "type": "object" } } } }, "400": { "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the request query is invalid." }, "401": { "description": "The request is not authorized." }, "403": { "description": "You do not have permission to access this resource." }, "404": { "description": "" }, "409": { "description": "" }, "410": { "description": "" }, "412": { "description": "" } }, "parameters": [ { "name": "integrationConfigurationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "propertyNames": { "maxLength": 256, "pattern": "^[\\w-]+$", "type": "string" }, "additionalProperties": {} } } } } } } } } }, "components": { "schemas": { "GlobalConfigItemValue": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "additionalProperties": { "$ref": "#/components/schemas/GlobalConfigItemValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/GlobalConfigItemValue" }, "type": "array" }, { "type": "boolean", "enum": [ false, true ] } ] } }, "securitySchemes": { "bearerToken": { "type": "http", "description": "Default authentication mechanism", "scheme": "bearer" }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.vercel.com/oauth/authorize", "tokenUrl": "https://api.vercel.com/oauth/access_token", "scopes": {} } } } } } }