# Create

> For AI agents: the complete documentation index is at https://buddy.works/llms.txt

`POST /workspaces/:workspace/artifacts/:artifact_id/versions/:version_id/commit`

Create a commit from uploaded files in a GIT artifact version

**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"
  /** The Version ID */
  version_id: string; // Example: "a9f84k2L"
}
```

## Body Parameters

```typescript
interface BodyParameters {
  /** The files to include in the commit, mapping previously uploaded files to their target paths in the repository */
  files: CommitGitFileRequest[];
  /** The commit message */
  message?: string;
}
```

## Response Body

```typescript
interface ResponseBody {
  /** 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 version (used in API endpoints) */
  id?: string;
  /** The version identifier (e.g., latest, v1.2.0, stable). For GIT artifacts it must be a full git ref: refs/heads/<branch> (e.g., refs/heads/main) or refs/tags/<tag> (e.g., refs/tags/v1.2.0). */
  version?: string;
  /** Size of the version content in bytes */
  size?: number;
  /** Version creation timestamp */
  created_date?: string;
  /** Whether the GitHub release synced into this version is a draft. Present only for GH_RELEASE artifacts */
  draft?: boolean;
  /** Whether the GitHub release synced into this version is a pre-release. Present only for GH_RELEASE artifacts */
  prerelease?: boolean;
  /** Git metadata for a GIT artifact version */
  git_metadata?: GitVersionMetadataView;
  /** Status of the version. READY when its content is available, COPYING while the content of the version given in 'from' is being copied into it, COPY_FAILED when that copy failed */
  status?: "READY" | "COPYING" | "COPY_FAILED";
  /** Note for this resource */
  note?: string;
  /** YAML note for AI agents operating on this resource */
  agent_note?: string;
  /** Direct URL to access the artifact version content. For CONTAINER artifacts, this is the registry URL (e.g., container.registry.sh/ttests/ubuntu:latest). For FILES artifacts, this is the HTTP server URL where the content is served (e.g., https://latest-my-artifact.bucket-1.registry.sh/). For TURSO artifacts, this is the database URL the SQL client connects to (e.g., https://v1-my-database-workspace.turso-1.registry.sh) */
  version_url?: string;
}
```

## Type Definitions

```typescript
interface CommitGitFileRequest {
  /** The target path of the file within the repository */
  path: string;
  /** The opaque upload reference returned by the file upload endpoint */
  upload_path: string;
}

interface GitVersionMetadataView {
  /** The type of git reference the version points to */
  ref_type?: "BRANCH" | "TAG";
  /** The short name of the git reference (branch or tag name) */
  short_name?: string;
  /** Whether this reference is the default ref of the repository */
  default_ref?: boolean;
  /** The full hash of the commit the version points to */
  commit_hash?: string;
  /** The abbreviated hash of the commit the version points to */
  short_commit_hash?: string;
  /** The name of the committer */
  committer_name?: string;
  /** The email of the committer */
  committer_email?: string;
  /** The commit timestamp */
  commit_date?: string;
  /** The name of the commit author */
  author_name?: string;
  /** The email of the commit author */
  author_email?: string;
  /** The authoring timestamp */
  author_date?: string;
}

```

## Request Example

```bash
curl -X POST "https://api.buddy.works/workspaces/:workspace/artifacts/:artifact_id/versions/:version_id/commit" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Add build artifacts",
  "files": [
    {
      "upload_path": "a1b2c3d4_app.js",
      "path": "dist/app.js"
    }
  ]
}'
```

## Response Example

**Status:** `201 Created`

```json
{
  "url": "https://api.buddy.works/workspaces/ttests/artifacts/x5169jL2/versions/0YgEzRGv",
  "html_url": "https://app.buddy.works/ttests/-/artifacts/x5169jL2/versions/0YgEzRGv",
  "version_url": "https://latest-my-artifact.bucket-1.registry.sh/",
  "id": "0YgEzRGv",
  "version": "latest",
  "size": 1048576,
  "created_date": "2024-01-20T10:30:00Z",
  "status": "READY",
  "note": "Notes about this resource",
  "agent_note": "my_custom_field: note for agent"
}
```

---
Original source: https://buddy.works/docs/api/artifacts/versions/commits/create