Git API Reference

Current status: this API surface is experimental. The recommended app bootstrap flow today is shift-cli create-app with local gh/git, with repository linkage stored on the Stage app.

All Git endpoints are served under the /api/v1/git prefix via the gateway. Most endpoints require a user parameter for OAuth token delegation through Passport.

Endpoints

Providers

Method	Path	Description
GET	/api/v1/git/providers	List registered providers
POST	/api/v1/git/providers	Register a provider
GET	/api/v1/git/providers/:idOrName	Get provider by ID or name
DELETE	/api/v1/git/providers/:idOrName	Delete provider

Repositories

Method	Path	Description
GET	/api/v1/git/repos	List connected repositories
POST	/api/v1/git/repos	Connect or create a repository
GET	/api/v1/git/repos/:idOrName	Get repository by ID or name
DELETE	/api/v1/git/repos/:idOrName	Disconnect repository
POST	/api/v1/git/repos/:idOrName/sync	Refresh repository metadata

Branches

Method	Path	Description
GET	/api/v1/git/repos/:id/branches	List branches (?user= required)
POST	/api/v1/git/repos/:id/branches	Create branch
DELETE	/api/v1/git/repos/:id/branches/:name	Delete branch (?user= required)

Commits

Method	Path	Description
GET	/api/v1/git/repos/:id/commits	List commits (?user=, ?branch=, ?limit=)
GET	/api/v1/git/repos/:id/commits/:sha	Get commit details (?user= required)
POST	/api/v1/git/repos/:id/commits	Create commit (programmatic)

Files

Method	Path	Description
GET	/api/v1/git/repos/:id/files	List directory (?user=, ?path=, ?ref=)
GET	/api/v1/git/repos/:id/files/*	Get file content (?user=, ?ref=)

Compare

Method	Path	Description
GET	/api/v1/git/repos/:id/compare/:base...:head	Compare two refs (?user= required)

Pull Requests

Method	Path	Description
GET	/api/v1/git/repos/:id/pulls	List PRs (?user=, ?state=)
POST	/api/v1/git/repos/:id/pulls	Create PR
GET	/api/v1/git/repos/:id/pulls/:number	Get PR details (?user= required)
POST	/api/v1/git/repos/:id/pulls/:number/merge	Merge PR

Webhooks

Method	Path	Description
POST	/api/v1/git/repos/:id/webhooks	Set up webhook
DELETE	/api/v1/git/repos/:id/webhooks	Remove webhook (?user= required)
POST	/api/v1/git/webhooks/receive	Incoming webhook endpoint (HMAC-verified)
GET	/api/v1/git/webhooks/events	List webhook events (?repositoryId=, ?limit=)

Examples

Register a Provider

curl -X POST http://localhost:3000/api/v1/git/providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "type": "github",
    "passportProviderId": "github-oauth"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4",
    "name": "github",
    "type": "github",
    "passportProviderId": "github-oauth",
    "created": "2026-03-05T12:00:00.000Z",
    "updated": "2026-03-05T12:00:00.000Z"
  }
}

Connect a Repository

curl -X POST http://localhost:3000/api/v1/git/repos \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "a1b2c3d4",
    "owner": "my-org",
    "repoName": "my-app",
    "user": "me@example.com"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "x9y8z7w6",
    "name": "my-org/my-app",
    "providerId": "a1b2c3d4",
    "owner": "my-org",
    "repoName": "my-app",
    "fullName": "my-org/my-app",
    "htmlUrl": "https://github.com/my-org/my-app",
    "defaultBranch": "main",
    "connectedBy": "me@example.com",
    "status": "active",
    "private": false,
    "created": "2026-03-05T12:00:00.000Z",
    "updated": "2026-03-05T12:00:00.000Z"
  }
}

List Branches

curl "http://localhost:3000/api/v1/git/repos/x9y8z7w6/branches?user=me@example.com"

Create a Pull Request

curl -X POST http://localhost:3000/api/v1/git/repos/x9y8z7w6/pulls \
  -H "Content-Type: application/json" \
  -d '{
    "user": "me@example.com",
    "title": "Add new feature",
    "body": "Implements the new feature as described in issue #42",
    "head": "feature/new-thing",
    "base": "main"
  }'

Compare Two Branches

curl "http://localhost:3000/api/v1/git/repos/x9y8z7w6/compare/main...feature/new-thing?user=me@example.com"

Create a Commit

curl -X POST http://localhost:3000/api/v1/git/repos/x9y8z7w6/commits \
  -H "Content-Type: application/json" \
  -d '{
    "user": "me@example.com",
    "branch": "feature/new-thing",
    "message": "Add README",
    "files": [
      { "path": "README.md", "content": "# My App" }
    ]
  }'

Set Up a Webhook

curl -X POST http://localhost:3000/api/v1/git/repos/x9y8z7w6/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "user": "me@example.com",
    "url": "https://app.the-shift.dev/api/v1/git/webhooks/receive"
  }'

Response Envelope

All responses follow the standard envelope format:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Repository not found: x9y8z7w6"
  }
}