API Overview

The .git API provides programmatic access to repositories, deployments, and team resources. All endpoints return JSON and require authentication via Bearer tokens. The API follows RESTful conventions and uses standard HTTP status codes.

Base URL: https://api.git.dev/v1

Authentication

Authenticate your requests using a Personal Access Token (PAT) or OAuth2 token. Include the token in the `Authorization` header:

Authorization: Bearer <YOUR_API_TOKEN>

Generate tokens via your dashboard under Settings → API → Tokens. Tokens expire after 90 days unless marked permanent.

Rate Limits

API requests are limited to prevent abuse. Limits vary by plan:

Plan	Requests/min	Burst
Starter	60	20
Pro	600	100
Enterprise	Custom	Custom

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

List Repositories

GET /v1/repositories

Returns a paginated list of repositories accessible to the authenticated user.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (max: 100)
sort	string	Sort by: `created`, `updated`, `name`

Example Response (200 OK)

{
  "data": [
    {
      "id": "repo_8f3k29d",
      "name": "frontend-app",
      "full_name": "acme/frontend-app",
      "visibility": "private",
      "created_at": "2024-11-15T08:22:00Z",
      "default_branch": "main"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 10
  }
}

Create Deployment

POST /v1/repositories/{repo_id}/deployments

Triggers a new deployment pipeline for the specified repository. Returns immediately with a deployment ID.

Path Parameters

Parameter	Type	Required	Description
repo_id	string	Yes	Repository slug or ID

Body Parameters

Parameter	Type	Required	Description
ref	string	Yes	Branch, tag, or commit SHA
environment	string		Target environment: `preview`, `staging`, `production`
variables	object		Key-value pairs for build env vars

Example Request

curl -X POST https://api.git.dev/v1/repositories/repo_8f3k29d/deployments \\
  -H "Authorization: Bearer $TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ref": "main",
    "environment": "production"
  }'

Example Response (201 Created)

{
  "id": "deploy_9x2m4p",
  "status": "queued",
  "url": "https://api.git.dev/v1/deployments/deploy_9x2m4p",
  "created_at": "2024-12-01T14:30:00Z"
}

Error Codes

.git uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with details:

Code	Meaning
`400`	Bad Request – Invalid parameters
`401`	Unauthorized – Missing or invalid token
`403`	Forbidden – Insufficient permissions
`404`	Not Found – Resource doesn't exist
`429`	Too Many Requests – Rate limit exceeded
`500`	Internal Server Error – Try again later

{
  "error": {
    "code": "invalid_ref",
    "message": "Branch 'feature-x' not found",
    "request_id": "req_7a2b9c"
  }
}