Projects API

Programmatic access to manage, deploy, and monitor your projects. All endpoints require authentication and follow standard REST conventions with JSON payloads.

Authentication

All API requests must include a valid Bearer token in the Authorization header:

Authorization: Bearer <your_api_key>

Generate tokens in Dashboard → Settings → API Keys. Tokens never expire unless rotated.

Endpoints

GET /v2/projects

Returns a paginated list of all projects accessible to the authenticated user or organization.

Query Parameters

Parameter	Type	Description
page number	integer	Page number (default: 1)
limit number	integer	Results per page (default: 20, max: 100)
status string	enum	Filter: active, archived, draft

curl -X GET "https://api.git.dev/v2/projects?limit=10" \\
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://api.git.dev/v2/projects', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const data = await res.json();

import requests
res = requests.get('https://api.git.dev/v2/projects',
    headers={'Authorization': f'Bearer {API_KEY}'})
data = res.json()

200 OK

{
  "projects": [
    {
      "id": "proj_8x2k9m",
      "name": "dashboard-frontend",
      "status": "active",
      "framework": "nextjs",
      "created_at": "2024-11-02T08:15:00Z"
    }
  ],
  "meta": { "page": 1, "total": 12 }
}

POST /v2/projects

Creates a new project and initializes the deployment pipeline.

Request Body REQUIRED

Field	Type	Description
name string	string	Project display name
repo_url string	string	Git repository HTTPS/SSH URL
framework string	enum	nextjs, react, vue, node, etc.
build_cmd string	string	Custom build command (optional)

201 Created

{
  "id": "proj_9a3b2c",
  "name": "new-app",
  "status": "pending",
  "url": "https://new-app.git.dev"
}

GET /v2/projects/:id

Retrieves detailed configuration, deployment status, and recent activity for a specific project.

200 OK

{
  "id": "proj_8x2k9m",
  "name": "dashboard-frontend",
  "config": {
    "build_cmd": "npm run build",
    "output_dir": ".next",
    "node_version": 18
  },
  "deployments": {
    "latest": "deploy_7721",
    "status": "success"
  }
}

PUT /v2/projects/:id

Updates project settings. Only provided fields are modified (partial update supported).

200 OK

Returns the updated project object.

DELETE /v2/projects/:id

Permanently deletes a project and all associated deployments, databases, and edge functions. This action is irreversible.

200 OK

{
  "success": true,
  "message": "Project deleted successfully."
}

Error Codes

Code	Status	Description
400	Bad Request	Invalid JSON syntax or missing required fields
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key lacks permission for this resource
404	Not Found	Project or endpoint does not exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal .git platform error

Example Error Response:

{ "error": { "code": "INVALID_PAYLOAD", "message": "Field 'repo_url' is required.", "docs": "https://docs.git.dev/errors#invalid_payload" } }

Rate Limits

API requests are limited to 1,000 requests per minute per API key. Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1699284000