# Update

`PATCH /workspaces/:workspace/artifacts/:artifact_Id`

Update artifact configuration

**Required Scopes:** `ARTIFACT_WRITE`

## URL Parameters

```typescript
interface URLParameters {
  /** The human-readable ID of the workspace */
  workspace: string; // Example: "my-company"
  /** The Artifact ID */
  artifact_Id: string; // Example: "x5169jL2"
}
```

## Body Parameters

```typescript
interface BodyParameters {
  /** The display name of the artifact. Can only be changed if artifact type is FILES. */
  name?: string;
  /** The human-readable identifier of the artifact */
  identifier?: string;
  /** Project reference for artifact creation/update */
  project?: ProjectReferenceView;
  /** Environment reference for artifact creation/update */
  environment?: EnvironmentReferenceView;
  /** The scope level of the artifact. Can only be changed to a higher level: ENVIRONMENT→PROJECT or WORKSPACE, PROJECT→WORKSPACE */
  scope?: string;
  /** Artifact authorization configuration. Password is only used in requests and not returned in responses. BASIC authorization can only be used with FILES type artifacts. */
  authorization?: AuthorizationView;
  /** Artifact permissions configuration */
  permissions?: ArtifactPermissionsView;
  /** List of pipelines allowed to access this artifact */
  allowed_pipelines?: AllowedPipelineView[];
  /** Set to `true` to allow all pipelines to use this artifact */
  pipelines_access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
  /** List of retention rules for automatic cleanup of artifact versions */
  retention_rules?: ArtifactRetentionRuleView[];
  /** List of sandboxes allowed to access this package */
  allowed_sandboxes?: AllowedSandboxView[];
  /** Default access level for all sandboxes */
  sandboxes_access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}
```

## Response Body

```typescript
interface ResponseBody {
  /** The type of artifact */
  type?: "CONTAINER" | "BUCKET" | "NPM" | "COMPOSER";
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The unique ID of the artifact */
  id?: number;
  /** The display name of the artifact */
  name?: string;
  /** The human-readable identifier of the artifact */
  identifier?: string;
  /** The scope level of the artifact */
  scope?: "WORKSPACE" | "PROJECT" | "ENVIRONMENT";
  /** Total size of all artifact versions in bytes */
  size?: number;
  /** Short representation of a project */
  project?: ShortProjectView;
  /** Short representation of an environment object */
  environment?: ShortEnvironmentView;
  /** Artifact authorization configuration. Password is only used in requests and not returned in responses. BASIC authorization can only be used with FILES type artifacts. */
  authorization?: AuthorizationView;
  /** Artifact permissions configuration */
  permissions?: ArtifactPermissionsView;
  /** List of pipelines allowed to access this artifact */
  allowed_pipelines?: AllowedPipelineView[];
  /** Set to `true` to allow all pipelines to use this artifact */
  pipelines_access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
  /** List of sandboxes allowed to access this package */
  allowed_sandboxes?: AllowedSandboxView[];
  /** Default access level for all sandboxes */
  sandboxes_access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
  /** Artifact creation timestamp */
  created_date?: string;
  /** List of retention rules for automatic cleanup of artifact versions */
  retention_rules?: ArtifactRetentionRuleView[];
}
```

## Type Definitions

```typescript
interface ProjectReferenceView {
  /** The name of the project */
  name: string;
}

interface EnvironmentReferenceView {
  /** The ID of the environment */
  id: number;
}

interface AuthorizationView {
  /** The type of authorization. BASIC can only be used with FILES type artifacts. */
  type: "NONE" | "BUDDY" | "BASIC";
  /** Username for BASIC auth (required when type is BASIC) */
  user?: string;
  /** Password for BASIC auth (required when type is BASIC) */
  password?: string;
}

interface ArtifactPermissionsView {
  /** Permission level for others */
  others?: "DENIED" | "READ_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT";
  /** List of user-specific permissions for the artifact */
  users?: ArtifactUserPermissionView[];
  /** List of group-specific permissions for the artifact */
  groups?: ArtifactGroupPermissionView[];
}

interface ArtifactUserPermissionView {
  /** User ID */
  id: number;
  /** Access level for the user */
  access_level: "DENIED" | "READ_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT";
}

interface ArtifactGroupPermissionView {
  /** Group ID */
  id: number;
  /** Access level for the group */
  access_level: "DENIED" | "READ_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT";
}

interface AllowedPipelineView {
  /** Project name */
  project: string;
  /** Pipeline identifier */
  pipeline: string;
  /** Access level for the allowed pipeline. Project repository targets: `DENIED`, `READ_ONLY`, `READ_WRITE`. Other targets: `DENIED`, `USE_ONLY` */
  access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}

interface ArtifactRetentionRuleView {
  /** The unique ID of the retention rule */
  id?: number;
  /** The type of retention rule */
  type?: "KEEP_ALL" | "KEEP_BY_COUNT" | "KEEP_BY_DATE";
  /** The value for the retention rule (e.g., number of versions to keep or number of days) */
  value?: number;
  /** Regex pattern to filter artifact versions by tag. Only matching versions are affected by this rule. */
  tag_filter?: string;
}

interface AllowedSandboxView {
  /** Project name */
  project: string;
  /** Sandbox identifier */
  sandbox: string;
  /** Access level for the allowed sandbox: `DENIED`, `READ_ONLY`, `READ_WRITE` */
  access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}

interface ShortProjectView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The human-readable ID of the project */
  name?: string;
  /** The Name of the project */
  display_name: string;
  /** The status of the project */
  status?: string;
  /** Indicates if this is a public project */
  access?: "PRIVATE" | "PUBLIC";
  /** The creation date of the project */
  create_date?: string;
}

interface ShortEnvironmentView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The name of the environment */
  name?: string;
  /** The human-readable identifier of the environment */
  identifier?: string;
  /** The ID of the environment */
  id?: number;
  /** The scope level of the environment */
  scope?: "PROJECT" | "WORKSPACE" | "ANY";
}

```

## Request Example

```bash
curl -X PATCH "https://api.buddy.works/workspaces/:workspace/artifacts/:artifact_Id" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "updated-artifact-name"
}'
```

## Response Example

**Status:** `200 Artifact updated successfully`

```json
{
  "url": "https://api.buddy.works/workspaces/ttests/artifacts/x5169jL2",
  "html_url": "https://app.buddy.works/ttests/-/artifacts/x5169jL2/versions",
  "id": "x5169jL2",
  "name": "Updated Artifact Name",
  "identifier": "my-app-artifact",
  "type": "BUCKET",
  "project": {
    "url": "https://api.buddy.works/workspaces/ttests/projects/my-project",
    "html_url": "https://app.buddy.works/ttests/projects/my-project",
    "name": "my-project",
    "display_name": "My Project"
  },
  "environment": {
    "url": "https://api.buddy.works/workspaces/ttests/projects/my-project/environments/nZrnl40Y",
    "html_url": "https://app.buddy.works/ttests/projects/my-project/environments/nZrnl40Y",
    "name": "staging",
    "identifier": "my-staging",
    "id": "nZrnl40Y",
    "scope": "PROJECT"
  },
  "scope": "WORKSPACE",
  "authorization": {
    "type": "NONE"
  },
  "permissions": {
    "others": "READ_ONLY",
    "users": [
      {
        "id": 42,
        "access_level": "READ_WRITE"
      }
    ],
    "groups": [
      {
        "id": 15,
        "access_level": "READ_ONLY"
      }
    ]
  },
  "size": 524288000,
  "created_date": "2024-01-15T10:30:00Z"
}
```

---
Original source: https://buddy.works/docs/api/artifacts/update