API Documentation

CodeVault REST API v1 — authenticate with a Personal Access Token.

Machine-readable spec

A complete OpenAPI 3.1 description of every /api/v1/* endpoint is served alongside this page. Codegen tools (openapi-generator, oapi-codegen), MCP servers, and AI agents can consume either format directly.

/openapi.yaml /openapi.json

Authentication

Create a token at /settings/tokens, then use it in requests:

Authorization: Bearer YOUR_TOKEN

Or via HTTP Basic Auth with your username and token as the password:

curl -u username:TOKEN https://your-instance/api/v1/user

Endpoints

User

GET/api/v1/userAuthenticated user
GET/api/v1/users/{username}User profile
GET/api/v1/user/reposRepos you can access

Repositories

GET/api/v1/repos/{owner}/{repo}Repo details
GET/api/v1/repos/{owner}/{repo}/contents?path=&ref=Raw file content
GET/api/v1/repos/{owner}/{repo}/blame?path=&ref=Blame for a file
GET/api/v1/repos/{owner}/{repo}/branchesList branches
POST/api/v1/repos/{owner}/{repo}/branchesCreate branch
DEL/api/v1/repos/{owner}/{repo}/branches/{branch}Delete branch

Issues

GET/api/v1/repos/{owner}/{repo}/issuesList issues
POST/api/v1/repos/{owner}/{repo}/issuesCreate issue
GET/api/v1/repos/{owner}/{repo}/issues/{number}Get issue
POST/api/v1/repos/{owner}/{repo}/issues/{number}/commentsComment

Pull Requests

GET/api/v1/repos/{owner}/{repo}/pullsList PRs
POST/api/v1/repos/{owner}/{repo}/pullsCreate PR
GET/api/v1/repos/{owner}/{repo}/pulls/{number}Get PR
GET/api/v1/repos/{owner}/{repo}/pulls/{number}/filesChanged files
POST/api/v1/repos/{owner}/{repo}/pulls/{number}/reviewsReview {event, body}
POST/api/v1/repos/{owner}/{repo}/pulls/{number}/commentsReview comment (inline/general)
POST/api/v1/repos/{owner}/{repo}/pulls/{number}/mergeMerge {strategy} (409 if protected)

Commit Status (CI/CD)

POST/api/v1/repos/{owner}/{repo}/statuses/{sha}Set status
GET/api/v1/repos/{owner}/{repo}/statuses/{sha}Get statuses

Packages

POST/api/v1/repos/{owner}/{repo}/packages/{type}Upload package
GET/api/v1/repos/{owner}/{repo}/packages/{type}/{name}/{version}/files/{file}Download

Roadmap & Milestones

GET/api/v1/repos/{owner}/{repo}/roadmapRoadmap milestones
GET/api/v1/repos/{owner}/{repo}/milestonesList milestones
POST/api/v1/repos/{owner}/{repo}/milestonesCreate (write scope)
PATCH/api/v1/repos/{owner}/{repo}/milestones/{id}Update state/release/order
GET/api/v1/repos/{owner}/{repo}/releasesList releases
GET/api/v1/orgs/{org}/roadmapOrg-wide roadmap

Feature Requests (community)

GET/api/v1/repos/{owner}/{repo}/feature-requestsList (most-voted first)
POST/api/v1/repos/{owner}/{repo}/feature-requestsSuggest {title, body} — needs suggest
POST/api/v1/repos/{owner}/{repo}/feature-requests/{number}/voteToggle vote — needs vote

Polls (community)

GET/api/v1/repos/{owner}/{repo}/pollsList with tallies + your choices
POST/api/v1/repos/{owner}/{repo}/polls/{id}/voteCast vote {options:[id]} — needs vote

Notifications

GET/api/v1/notificationsList (?unread=1&limit=)
POST/api/v1/notifications/{id}/readMark one read
POST/api/v1/notifications/readMark all read

Reactions

POST/api/v1/reactionsToggle {target_type, target_id, emoji}

Security & Supply-chain

GET/api/v1/repos/{owner}/{repo}/advisoriesDependency advisories
POST/api/v1/repos/{owner}/{repo}/advisories/{id}/autofixOpen an autofix PR
GET/api/v1/repos/{owner}/{repo}/dependenciesDependency inventory
GET/api/v1/repos/{owner}/{repo}/provenanceBuild/commit provenance
GET/api/v1/notary-keyCosign/notary public key

Deployments

GET/api/v1/repos/{owner}/{repo}/deploy-runsList deploy runs
POST/api/v1/repos/{owner}/{repo}/deploy-runsTrigger a deploy
POST/api/v1/repos/{owner}/{repo}/deploy-runs/{id}/advanceAdvance to next ring
POST/api/v1/repos/{owner}/{repo}/deploy-runs/{id}/rollbackRoll back

Community collaboration

Feature requests and polls honour the repository's community capability settings (maintainers grant suggest, discuss, vote, and create_poll per user and/or milestone). Reads follow repo visibility; a write you're not permitted returns 403.

# List feature requests (most-voted first)
curl -H "Authorization: Bearer TOKEN" \
     https://your-instance/api/v1/repos/OWNER/REPO/feature-requests

# Suggest one (needs the 'suggest' capability)
curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -d '{"title":"Dark mode","body":"Please add a dark theme"}' \
     https://your-instance/api/v1/repos/OWNER/REPO/feature-requests

# Upvote #12 (needs 'vote')
curl -X POST -H "Authorization: Bearer TOKEN" \
     https://your-instance/api/v1/repos/OWNER/REPO/feature-requests/12/vote

# List polls with live tallies + your own choices
curl -H "Authorization: Bearer TOKEN" \
     https://your-instance/api/v1/repos/OWNER/REPO/polls

# Cast a poll vote (needs 'vote'); single-choice keeps the first option
curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -d '{"options":[34]}' \
     https://your-instance/api/v1/repos/OWNER/REPO/polls/5/vote

Pagination

List endpoints support pagination via query parameters:

GET /api/v1/repos/{owner}/{repo}/issues?page=1&per_page=20

Response headers include:

  • X-Total-Count — total number of items
  • Link — next/prev page URLs

Git Operations

# Clone (HTTP)
git clone http://your-instance/owner/repo.git

# Clone (SSH, port 2222)
git clone ssh://git@your-instance:2222/owner/repo.git

# Push with token auth
git remote set-url origin http://username:TOKEN@your-instance/owner/repo.git

Docker Registry

Docker Registry v2 API is available at /v2/:

# Login
docker login your-instance

# Push
docker tag myimage your-instance/owner/repo:latest
docker push your-instance/owner/repo:latest

# Pull
docker pull your-instance/owner/repo:latest