Upload a project avatar
POST
https://api.vercel.com/v1/projects/{idOrName}/avatarUpload an image as the avatar of the project identified by
idOrName. The request body is the raw bytes of a JPG, PNG, or SVG image; the Content-Type header must declare which. SVG payloads are sanitized and optimized server-side before storage. The final SHA-1 of the stored bytes becomes the project's avatar value. The actual upload pipeline (validation, sanitization, S3 write, conditional updateProject, and event emission) lives in the shared @api/project-avatar-upload helper so it can be reused by background workers.Request
import { Vercel } from "@vercel/sdk";
const vercel = new Vercel({ bearerToken: "<YOUR_BEARER_TOKEN_HERE>",});
async function run() { const result = await vercel.projects.uploadProjectAvatar({ idOrName: "<value>", teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l", slug: "my-team-url-slug", });
console.log(result);}
run();Response
{ "accountId": "example_id", "alias": [ { "configuredBy": "A", "configuredChangedAt": "123", "createdAt": "123", "deployment": { "alias": [], "aliasAssigned": "123", "aliasError": { "code": "string", "message": "string" }, "aliasFinal": "string", "automaticAliases": [], "branchMatcher": { "pattern": "string", "type": "endsWith" }, "buildingAt": "123", "builds": [ { "dest": "string", "src": "string", "use": "string" } ], "checksConclusion": "canceled", "checksState": "completed", "connectBuildsEnabled": "false", "connectConfigurationId": "example_id", "createdAt": "123", "createdIn": "string", "creator": { "email": "user@example.com", "githubLogin": "string", "gitlabLogin": "string", "uid": "example_id", "username": "string" }, "deletedAt": "123", "deploymentHostname": "Example Name", "forced": "false", "id": "icfg_1234567890", "meta": "value", "monorepoManager": "string", "name": "Example Name", "oidcTokenClaims": { "aud": "string", "custom_environment_id": "example_id", "deployment_id": "example_id", "environment": "string", "iss": "string", "mfe_group_ids": [], "owner": "string", "owner_id": "example_id", "plan": "string", "project": "string", "project_id": "example_id", "scope": "string", "sub": "string" }, "plan": "enterprise", "previewCommentsEnabled": "false", "private": "false", "readyAt": "123", "readyState": "BLOCKED", "readySubstate": "PROMOTED", "requestedAt": "123", "target": "string", "teamId": "example_id", "type": "LAMBDAS", "url": "https://example.com", "userId": "example_id", "withCache": "false" }, "domain": "string", "environment": "preview", "gitBranch": "string", "redirect": "string", "redirectStatusCode": "301", "target": "PREVIEW" } ], "analytics": { "canceledAt": "123", "disabledAt": "123", "enabledAt": "123", "id": "icfg_1234567890", "paidAt": "123", "sampleRatePercent": "123", "spendLimitInDollars": "123" }, "appliedCve55182Migration": "false", "autoAssignCustomDomains": "false", "autoAssignCustomDomainsUpdatedBy": "string", "autoExposeSystemEnvs": "false", "avatar": "string", "avatarDarkMode": "string", "blobs": { "isDefaultApp": "false" }, "buildCommand": "string", "commandForIgnoringBuildStep": "string", "concurrencyBucketName": "Example Name", "connectBuildsEnabled": "false", "connectConfigurationId": "example_id", "connectConfigurations": [ { "aws": { "securityGroupId": "https://example.com", "subnetIds": [] }, "buildsEnabled": "false", "connectConfigurationId": "example_id", "createdAt": "123", "dc": "string", "envId": "example_id", "passive": "false", "updatedAt": "123" } ], "createdAt": "123", "creator": { "type": "user", "via": { "app": { "clientId": "example_id", "id": "icfg_1234567890" }, "type": "app" }, "user": { "id": "icfg_1234567890" } }, "crons": { "definitions": [ { "description": "string", "host": "vercel.com", "hostInferred": "false", "path": "/api/crons/sync-something?hello=world", "schedule": "0 0 * * *", "source": "api" } ], "deploymentId": "example_id", "disabledAt": "123", "enabledAt": "123", "updatedAt": "123" }, "customEnvironments": [ { "branchMatcher": { "pattern": "string", "type": "endsWith" }, "createdAt": "123", "currentDeploymentAliases": [], "description": "string", "domains": [ { "apexName": "Example Name", "createdAt": "123", "customEnvironmentId": "example_id", "gitBranch": "string", "name": "Example Name", "projectId": "example_id", "redirect": "string", "redirectStatusCode": "301", "updatedAt": "123", "verification": [ { "domain": "string", "reason": "Customer requested refund", "type": "string", "value": "string" } ], "verified": "false" } ], "id": "icfg_1234567890", "slug": "string", "type": "development", "updatedAt": "123" } ], "customerSupportCodeVisibility": "false", "dataCache": { "storageSizeBytes": "123", "unlimited": "false", "userDisabled": "false" }, "defaultResourceConfig": { "buildMachineElasticLastUpdated": "123", "buildMachineElasticReason": "basic-floor", "buildMachineElasticTransition": { "algorithmVersion": "string", "at": "123", "direction": "downgrade" }, "buildMachineSelection": "elastic", "buildMachineType": "basic", "buildQueue": { "configuration": "SKIP_NAMESPACE_QUEUE" }, "elasticConcurrencyEnabled": "false", "enableFunctionsBeta": "false", "fluid": "false", "functionDefaultMemoryType": "performance", "functionDefaultRegions": [], "functionDefaultTimeout": "123", "functionZeroConfigFailover": "false", "isNSNBDisabled": "false", "elasticBuildMachine": { "cores": "123", "label": "enhanced", "memory": "123" } }, "deploymentExpiration": { "deploymentsToKeep": "123", "expirationDays": "123", "expirationDaysCanceled": "123", "expirationDaysErrored": "123", "expirationDaysProduction": "123" }, "deploymentPolicy": { "deploymentSources": [ { "enabled": "false", "environments": [ { "target": "preview", "type": "system" } ], "sources": [] } ], "gitSources": [ { "enabled": "false", "environments": [ { "target": "preview", "type": "system" } ], "sources": [ { "org": "string", "provider": "bitbucket", "repo": "string" } ] } ] }, "devCommand": "string", "directoryListing": "false", "dismissedToasts": [ { "action": "accept", "dismissedAt": "123", "key": "string", "value": "string" } ], "enableAffectedProjectsDeployments": "false", "enableExternalRewriteCaching": "false", "enablePreviewFeedback": "false", "enableProductionFeedback": "false", "env": [ { "comment": "string", "configurationId": "example_id", "contentHint": { "storeId": "example_id", "type": "redis-url" }, "createdAt": "123", "createdBy": "string", "customEnvironmentIds": [], "decrypted": "false", "edgeConfigId": "example_id", "edgeConfigTokenId": "example_id", "gitBranch": "string", "id": "icfg_1234567890", "internalContentHint": { "encryptedValue": "string", "type": "flags-secret" }, "key": "string", "legacyValue": "string", "sunsetSecretId": "example_id", "target": [], "type": "encrypted", "updatedAt": "123", "updatedBy": "string", "value": "string", "visibility": "config", "vsmValue": "string" } ], "expiration": { "expiresAt": "123" }, "features": { "webAnalytics": "false" }, "framework": "actix-web", "gitComments": { "onCommit": "false", "onPullRequest": "false" }, "gitForkProtection": "false", "gitLFS": "false", "gitProviderOptions": { "consolidatedGitCommitStatus": { "enabled": "false", "propagateFailures": "false" }, "createDeployments": "disabled", "disableRepositoryDispatchEvents": "false", "gitCommitStatus": "false", "requireVerifiedCommits": "false" }, "hasActiveBranches": "false", "hasDeployments": "false", "id": "icfg_1234567890", "installCommand": "string", "internalRoutes": [ { "expiry": "123", "src": "string", "status": "123" } ], "ipBuckets": [ { "bucket": "string", "default": "false", "supportUntil": "123" } ], "jobs": { "flag-definitions-present": { "targets": [] }, "lint": { "targets": [] }, "mfe-config-present": { "targets": [] }, "typecheck": { "targets": [] } }, "lastAliasRequest": { "fromDeploymentId": "example_id", "fromRollingReleaseId": "example_id", "jobStatus": "failed", "requestedAt": "123", "toDeploymentId": "example_id", "type": "promote" }, "lastRollbackTarget": "value", "latestDeployments": [ { "alias": [], "aliasAssigned": "123", "aliasError": { "code": "string", "message": "string" }, "aliasFinal": "string", "automaticAliases": [], "branchMatcher": { "pattern": "string", "type": "endsWith" }, "buildingAt": "123", "builds": [ { "dest": "string", "src": "string", "use": "string" } ], "checksConclusion": "canceled", "checksState": "completed", "connectBuildsEnabled": "false", "connectConfigurationId": "example_id", "createdAt": "123", "createdIn": "string", "creator": { "email": "user@example.com", "githubLogin": "string", "gitlabLogin": "string", "uid": "example_id", "username": "string" }, "deletedAt": "123", "deploymentHostname": "Example Name", "forced": "false", "id": "icfg_1234567890", "meta": "value", "monorepoManager": "string", "name": "Example Name", "oidcTokenClaims": { "aud": "string", "custom_environment_id": "example_id", "deployment_id": "example_id", "environment": "string", "iss": "string", "mfe_group_ids": [], "owner": "string", "owner_id": "example_id", "plan": "string", "project": "string", "project_id": "example_id", "scope": "string", "sub": "string" }, "plan": "enterprise", "previewCommentsEnabled": "false", "private": "false", "readyAt": "123", "readyState": "BLOCKED", "readySubstate": "PROMOTED", "requestedAt": "123", "target": "string", "teamId": "example_id", "type": "LAMBDAS", "url": "https://example.com", "userId": "example_id", "withCache": "false" } ], "link": { "createdAt": "123", "deployHooks": [ { "createdAt": "123", "id": "icfg_1234567890", "name": "Example Name", "ref": "string", "url": "https://example.com" } ], "gitCredentialId": "example_id", "org": "string", "productionBranch": "string", "repo": "string", "repoId": "123", "repoOwnerId": "123", "sourceless": "false", "type": "github", "updatedAt": "123" }, "live": "false", "microfrontends": { "defaultRoute": "string", "enabled": "true", "freeProjectForLegacyLimits": "false", "groupIds": [], "isDefaultApp": "true", "updatedAt": "123" }, "name": "Example Name", "nodeVersion": "10.x", "oidcTokenConfig": { "enabled": "false", "issuerMode": "global" }, "optionsAllowlist": { "paths": [ { "value": "string" } ] }, "outputDirectory": "string", "passiveConnectConfigurationId": "example_id", "passport": { "connectorId": "example_id", "deploymentType": "all" }, "passwordProtection": { "deploymentType": "all" }, "paused": "false", "permissions": { "accessGroup": [], "agent": [], "aiGatewayApiKey": [], "aiGatewayApiKeyBypassAll": [], "aiGatewayApiKeyOwnedBySelf": [], "aiGatewayApiKeySpendAttribution": [], "aiGatewayApiKeyZdrExemption": [], "aiGatewayBudget": [], "aiGatewayCredits": [], "aiGatewayGuardrails": [], "aiGatewayPrivateModels": [], "aiGatewayRules": [], "aiGatewaySettings": [], "aiGatewayTranscripts": [], "aiGatewayTranscriptsSettings": [], "aiGatewayUsage": [], "aiGatewayVirtualModelConfigs": [], "alertRules": [], "alerts": [], "aliasGlobal": [], "aliasProject": [], "aliasProtectionBypass": [], "analytics": [], "analyticsSampling": [], "analyticsUsage": [], "apiKey": [], "apiKeyAiGateway": [], "apiKeyOwnedBySelf": [], "auditLog": [], "automation": [], "billingAddress": [], "billingInformation": [], "billingInvoice": [], "billingInvoiceEmailRecipient": [], "billingInvoiceLanguage": [], "billingPlan": [], "billingPurchaseOrder": [], "billingRefund": [], "billingTaxId": [], "blob": [], "blobStoreTokenSet": [], "budget": [], "buildMachine": [], "buildMachineDefault": [], "bulkRedirects": [], "cacheArtifact": [], "cacheArtifactUsageEvent": [], "ciInvocations": [], "ciLogs": [], "codeChecks": [], "codeOwners": [], "concurrentBuilds": [], "connect": [], "connectConfiguration": [], "connectConfigurationLink": [], "connectLogs": [], "connexClient": [], "connexClientProject": [], "connexContact": [], "connexInstallation": [], "connexToken": [], "cursorOriginInstallation": [], "dataCacheBillingSettings": [], "dataCacheNamespace": [], "defaultDeploymentProtection": [], "deployment": [], "deploymentBuildLogs": [], "deploymentCheck": [], "deploymentCheckPreview": [], "deploymentCheckReRunFromProductionBranch": [], "deploymentPolicy": [], "deploymentPreview": [], "deploymentPrivate": [], "deploymentProductionGit": [], "deploymentPromote": [], "deploymentProtectionException": [], "deploymentRollback": [], "deploymentV0": [], "domain": [], "domainAcceptDelegation": [], "domainAuthCodes": [], "domainCertificate": [], "domainCheckConfig": [], "domainMove": [], "domainPurchase": [], "domainRecord": [], "domainTransferIn": [], "drain": [], "edgeCacheNamespace": [], "edgeConfig": [], "edgeConfigItem": [], "edgeConfigSchema": [], "edgeConfigToken": [], "endpointVerification": [], "environments": [], "event": [], "fileUpload": [], "flagsExplorerSubscription": [], "gitCredentialGrant": [], "gitRepository": [], "imageOptimizationNewPrice": [], "integration": [], "integrationAccount": [], "integrationConfiguration": [], "integrationConfigurationProjects": [], "integrationConfigurationRole": [], "integrationConfigurationTransfer": [], "integrationDeploymentAction": [], "integrationEvent": [], "integrationLog": [], "integrationPullRequest": [], "integrationResource": [], "integrationResourceData": [], "integrationResourceReplCommand": [], "integrationResourceSecrets": [], "integrationSSOSession": [], "integrationStoreTokenSet": [], "integrationStrict": [], "integrationVercelConfigurationOverride": [], "ipBlocking": [], "job": [], "jobGlobal": [], "kmsIssuer": [], "kmsProjectGrant": [], "logDrain": [], "logs": [], "logsPreset": [], "marketplaceBillingData": [], "marketplaceExperimentationEdgeConfigData": [], "marketplaceExperimentationItem": [], "marketplaceFlexCommit": [], "marketplaceInstallationMember": [], "marketplaceInvoice": [], "marketplaceSettings": [], "messageboard": [], "messageboardSpace": [], "messageboardTask": [], "Monitoring": [], "monitoringAlert": [], "monitoringChart": [], "monitoringQuery": [], "monitoringSettings": [], "notificationCustomerBudget": [], "notificationDeploymentFailed": [], "notificationDomainConfiguration": [], "notificationDomainExpire": [], "notificationDomainMoved": [], "notificationDomainPurchase": [], "notificationDomainRenewal": [], "notificationDomainTransfer": [], "notificationDomainUnverified": [], "NotificationMonitoringAlert": [], "notificationPaymentFailed": [], "notificationPreferences": [], "notificationStatementOfReasons": [], "notificationUsageAlert": [], "oauth2Application": [], "oauth2Connection": [], "observabilityConfiguration": [], "observabilityData": [], "observabilityFunnel": [], "observabilityNotebook": [], "oidcFederationPolicy": [], "onDemandBuild": [], "onDemandConcurrency": [], "openTelemetryEndpoint": [], "optionsAllowlist": [], "organization": [], "organizationDomain": [], "organizationTeam": [], "ownEvent": [], "pageIntegrity": [], "passwordProtection": [], "passwordProtectionInvoiceItem": [], "paymentMethod": [], "permissions": [], "postgres": [], "postgresStoreTokenSet": [], "previewDeploymentSuffix": [], "privateCloudAccount": [], "privateLinkEndpoint": [], "productionAliasProtectionBypass": [], "productionShareableLink": [], "project": [], "projectAccessGroup": [], "projectAnalyticsSampling": [], "projectAnalyticsUsage": [], "projectCheck": [], "projectCheckRun": [], "projectDeploymentExpiration": [], "projectDeploymentHook": [], "projectDeploymentProtectionStrict": [], "projectDomain": [], "projectDomainCheckConfig": [], "projectDomainMove": [], "projectDomainVerify": [], "projectEnvVars": [], "projectEnvVarsProduction": [], "projectEnvVarsUnownedByIntegration": [], "projectEvent": [], "projectFlags": [], "projectFlagsProduction": [], "projectFlagsSdkKey": [], "projectFromV0": [], "projectId": [], "projectIntegrationConfiguration": [], "projectLink": [], "projectMember": [], "projectMonitoring": [], "projectOIDCToken": [], "projectPermissions": [], "projectProductionBranch": [], "projectProtectionBypass": [], "projectRollingRelease": [], "projectRoutes": [], "projectSetting": [], "projectSupportCase": [], "projectSupportCaseComment": [], "projectTier": [], "projectTransfer": [], "projectTransferIn": [], "projectTransferOut": [], "projectTransferRequest": [], "projectUsage": [], "proTrialOnboarding": [], "rateLimit": [], "redis": [], "redisStoreTokenSet": [], "remoteCaching": [], "repository": [], "samlConfig": [], "schedule": [], "seawallConfig": [], "secret": [], "securityConfig": [], "securityPlusConfiguration": [], "sensitiveEnvironmentVariablePolicy": [], "setting": [], "shareableLink": [], "shareableLinkStrict": [], "sharedEnvVarConnection": [], "sharedEnvVars": [], "sharedEnvVarsProduction": [], "skewProtection": [], "space": [], "spaceRun": [], "storeIsLocked": [], "storeTokenSetSensitive": [], "storeTransfer": [], "supportCase": [], "supportCaseComment": [], "team": [], "teamAccessRequest": [], "teamFellowMembership": [], "teamGitExclusivity": [], "teamInvite": [], "teamInviteCode": [], "teamInviteLink": [], "teamJoin": [], "teamMemberMfaStatus": [], "teamMicrofrontends": [], "teamOwnMembership": [], "teamOwnMembershipDisconnectSAML": [], "teamSudo": [], "teamTokenInvalidation": [], "token": [], "toolbarComment": [], "trustedIps": [], "trustedSources": [], "usage": [], "usageCycle": [], "user": [], "userConnection": [], "userMfaConfiguration": [], "userPreference": [], "userSudo": [], "v0Chat": [], "vcrRepository": [], "vercelAppInstallation": [], "vercelAppInstallationRequest": [], "vercelAuth": [], "vercelRun": [], "vpcPeeringConnection": [], "webAnalytics": [], "webAnalyticsPlan": [], "webAuthn": [], "webhook": [], "webhook-event": [], "workflowRunData": [] }, "productionDeploymentsFastLane": "false", "protectedSourcemaps": "false", "protectionBypass": "value", "protectionConfig": { "sandboxUrls": { "inheritDeploymentProtection": "false" } }, "resourceConfig": { "buildMachineElasticLastUpdated": "123", "buildMachineElasticReason": "basic-floor", "buildMachineElasticTransition": { "algorithmVersion": "string", "at": "123", "direction": "downgrade" }, "buildMachineSelection": "elastic", "buildMachineType": "basic", "buildQueue": { "configuration": "SKIP_NAMESPACE_QUEUE" }, "elasticConcurrencyEnabled": "false", "enableFunctionsBeta": "false", "fluid": "false", "functionDefaultMemoryType": "performance", "functionDefaultRegions": [], "functionDefaultTimeout": "123", "functionZeroConfigFailover": "false", "isNSNBDisabled": "false", "elasticBuildMachine": { "cores": "123", "label": "enhanced", "memory": "123" } }, "rollbackDescription": { "createdAt": "123", "description": "string", "userId": "example_id", "username": "string" }, "rollingRelease": { "canaryResponseHeader": "false", "gate": { "action": "pause", "checks": [ { "excludePaths": [], "excludeStatusCodes": [], "ingestWatermarkSeconds": "30", "significanceLevel": "0.05", "type": "error-rate-5xx" } ], "dryRun": "false", "enabled": "false", "failureThreshold": "3", "windowSize": "5" }, "stages": [ { "duration": "600", "linearShift": "false", "requireApproval": "false", "targetPercentage": "25" } ], "target": "production" }, "rootDirectory": "string", "sandbox": { "failoverRegions": [], "region": "arn1" }, "security": { "attackModeActiveUntil": "123", "attackModeEnabled": "false", "attackModeUpdatedAt": "123", "botIdEnabled": "false", "firewallBypassIps": [], "firewallConfigVersion": "123", "firewallEnabled": "false", "firewallSeawallEnabled": "false", "firewallUpdatedAt": "123", "ja3Enabled": "false", "ja4Enabled": "false", "log_headers": [], "managedRules": { "ai_bots": { "action": "challenge", "active": "false" }, "bot_filter": { "action": "challenge", "active": "false" }, "owasp": { "action": "challenge", "active": "false" }, "traffic_sources": { "action": "challenge", "active": "false" }, "vercel_ruleset": { "action": "challenge", "active": "false" } }, "pageIntegrityEnabled": "false", "rulesets": "value" }, "serverlessFunctionZeroConfigFailover": "false", "services": [ { "framework": "actix-web", "runtime": "string", "serviceName": "Example Name", "serviceType": "cron" } ], "skewProtectionAllowedDomains": [], "skewProtectionBoundaryAt": "123", "skewProtectionMaxAge": "123", "skipGitConnectDuringLink": "false", "sourceFilesOutsideRootDirectory": "false", "speedInsights": { "canceledAt": "123", "dataReceivedAt": "123", "disabledAt": "123", "enabledAt": "123", "hasData": "false", "id": "icfg_1234567890", "paidAt": "123" }, "ssoProtection": { "april2026SecurityIncidentMigrationAppliedFrom": "all", "cve55182MigrationAppliedFrom": "all", "deploymentType": "all" }, "staticIps": { "builds": "false", "enabled": "false", "regions": [] }, "targets": "value", "tier": "priority", "tracing": { "domains": "string", "ignorePaths": [], "samplingRules": [ { "destination": "external", "env": "preview", "rate": "123", "requestPath": "string" } ] }, "transferCompletedAt": "123", "transferredFromAccountId": "example_id", "transferStartedAt": "123", "transferToAccountId": "example_id", "trustedIps": { "addresses": [ { "note": "string", "value": "string" } ], "deploymentType": "all", "protectionMode": "additional" }, "trustedSources": { "enableVercelCiSameRepository": "false", "oidcProviders": "value", "projects": "value" }, "updatedAt": "123", "usageStatus": { "bypassThrottleUntil": "123", "exceededAllowanceUntil": "123", "kind": "flat", "teamThrottled": "false", "throttled": "false" }, "v0": "false", "v0Created": "false", "webAnalytics": { "canceledAt": "123", "disabledAt": "123", "enabledAt": "123", "hasData": "true", "id": "icfg_1234567890" }}AuthorizationbearerToken
Default authentication mechanism
200Success
Retention policies for deployments. These are enforced at the project level, but we also maintain an instance of this at the team level as a default policy that gets applied to new projects.
Project shape.
null on a rule list clears the project's override for that rule type (fall back to team for every env); omitting is equivalent. Setting deploymentPolicy itself to null clears every override at once. Kept structurally distinct from {@link TeamDeploymentPolicy} so the two storage locations don't share a type by accident.Password protection settings returned without the secret password hash.
Requested and authorized operations when
checkPermissions is used. Legacy includePermissions responses contain a broader, non-authoritative permission summary.Description of why a project was rolled back, and by whom. Note that lastAliasRequest contains the from/to details of the rollback.
Project-level rolling release configuration that defines how deployments should be gradually rolled out
400One of the provided values in the request query is invalid.
401The request is not authorized.
403You do not have permission to access this resource.
404Error
410Error
413Error
415Error