headquarter/docs/api/repositories.md

Repositories API

Git repository and file management endpoints.

Authentication

All endpoints require authentication (session cookie).

---

GET /projects/{project_id}/repositories

Description: List repositories in a project.

Response

Success (200 OK)

[
  {
    "id": "uuid",
    "name": "my-repo",
    "clone_url": "https://github.com/user/repo.git",
    "is_mirror": true,
    "project_id": "uuid",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

---

POST /projects/{project_id}/repositories

Description: Create a new repository.

Request

Request Body

{
  "name": "my-repo",
  "remote_url": "https://github.com/user/repo.git",
  "is_mirror": false
}

Field	Type	Required	Description
name	string	Yes	Repository name
remote_url	string	No	Remote URL to clone from
is_mirror	boolean	No	Create mirror clone (default: false)

Response

Success (201 Created)

{
  "id": "uuid",
  "name": "my-repo",
  "clone_url": "https://github.com/user/repo.git",
  "is_mirror": false,
  "project_id": "uuid",
  "created_at": "2024-01-01T00:00:00Z"
}

URL Parsing Suggestion (422 Unprocessable Entity)

If the URL appears to be a browser URL:

{
  "detail": "URL appears to be a browser URL, not a git clone URL",
  "suggested_url": "https://github.com/user/repo.git",
  "original_url": "https://github.com/user/repo/tree/main",
  "error_code": "URL_NEEDS_PARSING"
}

---

DELETE /projects/{project_id}/repositories/{id}

Description: Delete a repository.

Response

Success (204 No Content)

Warning: Permanently deletes the repository from disk. Cannot be undone.

---

POST /projects/{project_id}/repositories/parse-url

Description: Parse and validate a git URL.

Request

Request Body

{
  "url": "https://github.com/user/repo/tree/main"
}

Response

Success (200 OK)

{
  "original_url": "https://github.com/user/repo/tree/main",
  "base_url": "https://github.com/user/repo.git",
  "is_valid_clone_url": false,
  "needs_parsing": true,
  "host": "github.com",
  "message": "This URL contains a branch path. The repository URL is: https://github.com/user/repo.git"
}

---

GET /projects/{project_id}/repositories/{id}/files

Description: List files in a directory.

Request

Query Parameters

Parameter	Type	Required	Description
branch	string	No	Branch name (default: repository default)
path	string	No	Directory path (default: root)

Response

Success (200 OK)

{
  "path": "src",
  "branch": "main",
  "entries": [
    {
      "name": "components",
      "type": "directory",
      "path": "src/components"
    },
    {
      "name": "main.py",
      "type": "file",
      "path": "src/main.py",
      "size": 1234,
      "last_commit": {
        "hash": "abc123",
        "message": "Initial commit",
        "author": "John Doe",
        "date": "2024-01-01T00:00:00Z"
      }
    }
  ]
}

---

GET /projects/{project_id}/repositories/{id}/files/content

Description: Get file content.

Request

Query Parameters

Parameter	Type	Required	Description
branch	string	Yes	Branch name
path	string	Yes	File path

Response

Success (200 OK)

{
  "path": "src/main.py",
  "branch": "main",
  "content": "function hello() {\n  return 'world';\n}",
  "size": 42,
  "encoding": "utf-8",
  "language": "python",
  "is_binary": false
}

Binary File (200 OK)

{
  "path": "image.png",
  "branch": "main",
  "content": null,
  "size": 12345,
  "encoding": null,
  "language": null,
  "is_binary": true
}

---

POST /projects/{project_id}/repositories/{id}/files/content

Description: Update file content and commit.

Request

Request Body

{
  "path": "src/main.py",
  "branch": "main",
  "content": "new content",
  "commit_message": "Update file",
  "author_name": "User",
  "author_email": "user@example.com"
}

Field	Type	Required	Description
path	string	Yes	File path
branch	string	Yes	Branch name
content	string	Yes	New file content
commit_message	string	Yes	Commit message
author_name	string	Yes	Author name
author_email	string	Yes	Author email

Response

Success (200 OK)

{
  "commit_hash": "def789",
  "message": "Update file",
  "branch": "main"
}

---

GET /projects/{project_id}/repositories/{id}/branches

Description: List branches.

Response

Success (200 OK)

{
  "branches": [
    {
      "name": "main",
      "is_default": true,
      "last_commit": {
        "hash": "abc123",
        "message": "Initial commit",
        "date": "2024-01-01T00:00:00Z"
      }
    }
  ],
  "default_branch": "main"
}

---

GET /projects/{project_id}/repositories/{id}/history

Description: Get commit history.

Request

Query Parameters

Parameter	Type	Required	Description
branch	string	No	Branch name (default: all branches)
max_count	integer	No	Maximum commits to return (default: 1000)

Response

Success (200 OK)

{
  "commits": [
    {
      "hash": "abc123",
      "author_name": "John Doe",
      "author_email": "john@example.com",
      "author_date": "2024-01-01T00:00:00Z",
      "message": "Initial commit",
      "refs": ["HEAD", "main"]
    }
  ],
  "branch": "main",
  "total_count": 50
}

---

GET /projects/{project_id}/repositories/{id}/commits/{hash}

Description: Get commit details.

Response

Success (200 OK)

{
  "hash": "abc123",
  "author_name": "John Doe",
  "author_email": "john@example.com",
  "author_date": "2024-01-01T00:00:00Z",
  "committer_name": "John Doe",
  "committer_email": "john@example.com",
  "commit_date": "2024-01-01T00:00:00Z",
  "message": "Initial commit",
  "stats": {
    "files_changed": 2,
    "insertions": 10,
    "deletions": 0
  },
  "diff": "diff --git a/file.txt b/file.txt\n..."
}