Repository Management

This guide covers how to manage repositories using the CommitKey API, including creating, updating, and deleting repositories.

Creating Repositories

Basic Repository Creation

curl -X POST https://api.commitkey.dev/v1/repositories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-repository",
    "description": "A sample repository",
    "private": true
  }'

Repository with Initial Content

curl -X POST https://api.commitkey.dev/v1/repositories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-repository",
    "description": "A sample repository",
    "private": true,
    "initialFiles": [
      {
        "path": "README.md",
        "content": "# My Repository\n\nThis is my repository."
      }
    ]
  }'

Listing Repositories

Get All Repositories

curl -X GET https://api.commitkey.dev/v1/repositories \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Specific Repository

curl -X GET https://api.commitkey.dev/v1/repositories/my-repository \
  -H "Authorization: Bearer YOUR_API_KEY"

Updating Repositories

Update Repository Settings

curl -X PATCH https://api.commitkey.dev/v1/repositories/my-repository \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "private": false
  }'

File Operations

Create or Update Files

curl -X POST https://api.commitkey.dev/v1/repositories/my-repository/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "src/index.js",
    "content": "console.log(\"Hello, World!\");",
    "message": "Add initial JavaScript file",
    "author": {
      "name": "Your Name",
      "email": "your.email@example.com"
    }
  }'

Delete Files

curl -X DELETE https://api.commitkey.dev/v1/repositories/my-repository/files/src/index.js \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Remove unnecessary file",
    "author": {
      "name": "Your Name",
      "email": "your.email@example.com"
    }
  }'

Branch Management

Create Branch

curl -X POST https://api.commitkey.dev/v1/repositories/my-repository/branches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "feature-branch",
    "base": "main"
  }'

List Branches

curl -X GET https://api.commitkey.dev/v1/repositories/my-repository/branches \
  -H "Authorization: Bearer YOUR_API_KEY"

Commit History

Get Commit History

curl -X GET https://api.commitkey.dev/v1/repositories/my-repository/commits \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Specific Commit

curl -X GET https://api.commitkey.dev/v1/repositories/my-repository/commits/COMMIT_SHA \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Repository Naming

• Use lowercase letters and hyphens
• Be descriptive but concise
• Avoid special characters

File Organization

• Use clear directory structures
• Include meaningful README files
• Follow language-specific conventions

Commit Messages

• Use clear, descriptive messages
• Follow conventional commit format
• Include context when necessary

Error Handling

Common errors and how to handle them:

Repository Already Exists

{
  "error": {
    "code": "REPOSITORY_EXISTS",
    "message": "A repository with this name already exists"
  }
}

Invalid Repository Name

{
  "error": {
    "code": "INVALID_REPOSITORY_NAME",
    "message": "Repository name contains invalid characters"
  }
}

Next Steps

• AI Agent Integration - Integrate with AI agents
• API Reference - Complete API documentation
• Webhooks - Set up real-time notifications