REST API Reference

Welcome to the official .git REST API documentation. This reference provides a complete guide to interacting with our platform programmatically. All endpoints are accessible via HTTPS and return JSON responses.

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

All requests require authentication via Bearer token. Responses follow standard HTTP status codes and include consistent error formatting. Pagination is supported for list endpoints using cursor-based navigation.

Authentication

The .git API uses API keys and OAuth 2.0 for authentication. All requests must include an Authorization header.

API Key Authentication

Generate your API key from the dashboard settings. Include it in the request header:

Request Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

For server-to-server integration, use service account keys with scoped permissions. OAuth is recommended for user-facing applications.

Rate Limits

API requests are rate-limited to ensure fair usage and platform stability. Limits vary by plan:

Free Tier: 60 requests/minute

Pro Tier: 600 requests/minute

Enterprise: Custom limits (up to 5,000 req/min)

Rate limit headers are included in every response:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests remaining in window
X-RateLimit-Reset: Unix timestamp when window resets

Exceeding the limit returns a 429 Too Many Requests status with a Retry-After header.

Error Handling

The API uses standard HTTP status codes and returns detailed error objects:

Error Response Format
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is expired or revoked.",
    "status": 401,
    "details": {
      "request_id": "req_8x92kd1m"
    }
  }
}

400

Bad Request - Malformed syntax

401

Unauthorized - Invalid credentials

403

Forbidden - Insufficient permissions

404

Not Found - Resource doesn't exist

422

Unprocessable - Validation failed

429

Too Many Requests - Rate limited

Repositories

GET /repositories List all accessible repositories

Query Parameters

Parameter	Type	Description
owner	string	Filter by owner username or org slug
visibility	string	`public`, `private`, or `all`
cursor	string	Pagination cursor from previous response
limit	integer	Results per page (max 100, default 30)

Response

200 OK
{
  "data": [
    {
      "id": "repo_9x82m",
      "name": "backend-api",
      "full_name": "acme/backend-api",
      "private": true,
      "default_branch": "main",
      "created_at": "2024-11-15T08:22:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true
  }
}

POST /repositories Create a new repository

Request Body

Field	Type	Required	Description
name	string	Required	Repository name (3-30 chars)
owner	string	Required	Target user or organization slug
private	boolean	Optional	Visibility flag (default: true)
description	string	Optional	Markdown description

Response

201 Created
{
  "id": "repo_4k29p",
  "name": "new-service",
  "status": "initializing",
  "clone_url": "https://git.dev/acme/new-service.git"
}

Deployments

POST /deployments Trigger a new deployment

Request Body

Field	Type	Required	Description
repo_id	string	Required	Target repository ID
branch	string	Required	Git branch to deploy
env	string	Optional	`preview`, `staging`, `production`
strategy	string	Optional	`instant`, `canary`, `blue_green`

Response

200 OK
{
  "id": "dep_7x92m",
  "status": "queued",
  "url": "https://preview-7x92m.git.dev",
  "created_at": "2025-01-20T14:30:00Z",
  "progress": 0
}

Webhooks

Configure HTTP callbacks for real-time event notifications. Supported events include repo.push, deploy.success, deploy.failed, and pr.merged.

Webhook Payload Example
{
  "event": "deploy.success",
  "id": "evt_2k91x",
  "timestamp": "2025-01-20T14:35:22Z",
  "data": {
    "deployment_id": "dep_7x92m",
    "url": "https://prod.acme.git.dev",
    "duration_ms": 2400
  }
}

All webhook requests include a X-Signature-256 header for HMAC validation. Verify payloads using your webhook secret.

SDKs & Libraries

Official client libraries are available for rapid integration:

npm install @git/dev-sdk (TypeScript/Node.js)
pip install git-sdk (Python)
go get github.com/git-sdk/go (Go)
gem install git-sdk (Ruby)

Community-maintained packages exist for PHP, Java, and C#. Full SDK documentation is available in the developer portal.