DEVELOPER PORTAL & API SPECIFICATION

Git for Prompts Developer Reference

Integrate prompt version control, automated diffs, and evaluation pipelines directly into your CI/CD workflows, terminal sessions, or AI agent runtimes via our CLI, REST API, and Model Context Protocol (MCP) server.

OpenAPI 3.1.0 Spec MCP Manifest (JSON)llms.txt for Agents

1. Command Line Interface (CLI)

The official CLI works completely offline with a local SQLite database in your repository (.gitforprompts/) and syncs securely to Git for Prompts cloud when authenticated.

# 1. Initialize local repository in your current directory

$ npx gitforprompts init

# 2. Stage and commit a prompt bundle locally

$ npx gitforprompts commit -m "Refactor system prompt to enforce strict JSON output"

# 3. View visual diff between two commits or against HEAD

$ npx gitforprompts diff HEAD~1

# 4. Push local changes to cloud repository

$ npx gitforprompts push <promptId> prompt.bundle.json

# 5. Pull latest cloud snapshot into your local workspace

$ npx gitforprompts pull <promptId>

2. API Authentication & Scopes

All REST API and MCP requests require an API key passed in the Authorization header as a Bearer token. Generate keys inside your API Keys Dashboard.

Authorization: Bearer gfp_live_your_secret_api_key_here

prompts:read

Fetch prompt repositories, version history, and active bundles.

prompts:write

Create new prompt repositories and configure evaluation settings.

versions:write

Push new immutable prompt version snapshots from CLI or CI runners.

3. REST API Endpoints

GET/api/v1/prompts?name=<name>

Resolve a prompt name to its unique ID for the authenticated key owner.

curl -H "Authorization: Bearer $GFP_API_KEY" \
  "https://gitforprompts.vercel.app/api/v1/prompts?name=customer-support-agent"

GET/api/v1/prompts/:id/latest

Retrieve the latest active version snapshot with optional runtime variable interpolation via query params (?variables[user_name]=Alice).

curl -H "Authorization: Bearer $GFP_API_KEY" \
  "https://gitforprompts.vercel.app/api/v1/prompts/pr_abc123/latest?variables[user_name]=Alice"

POST/api/v1/prompts/:id/versions

Push a new immutable version snapshot. Protected by advisory transactional database locks to prevent concurrent sequence collisions.

curl -X POST \
  -H "Authorization: Bearer $GFP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"You are a billing specialist...","commitMessage":"Update refund escalation policy"}' \
  "https://gitforprompts.vercel.app/api/v1/prompts/pr_abc123/versions"

4. Rate Limiting & RFC Headers

To protect service availability and prevent token exhaustion, Git for Prompts implements multi-layered token-bucket rate limiting backed by distributed Redis.

Standard Read / Query Limit

60 requests per minute per client IP address across all read endpoints.

Expensive Mutation Limit

20 version creations per minute per API key to ensure database consistency.

Every API response includes standard RFC rate limit headers:

RateLimit-Limit: 60

RateLimit-Remaining: 59

RateLimit-Reset: 60

# On 429 status code:

Retry-After: 60

5. Structured Errors & Agent Self-Healing

All error responses return machine-readable status codes and human-understandable hint directives allowing autonomous AI coding agents (Claude, Cursor, Devin) to self-heal when encountering 400, 401, 404, or 429 errors.

{
  "error": "Prompt not found",
  "code": "PROMPT_NOT_FOUND",
  "hint": "Verify that the prompt ID exists and is owned by the authenticated account. You can discover prompts using GET /api/v1/prompts?name=<name>."
}

6. Model Context Protocol (MCP) Setup

Git for Prompts natively supports Anthropic's open Model Context Protocol. Connect Cursor, Claude Desktop, or Windsurf directly to inspect prompts and run evaluations inside your chat agent.

Cursor / Claude Desktop Config (.cursor/mcp.json)

{
  "mcpServers": {
    "gitforprompts": {
      "url": "https://gitforprompts.vercel.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer gfp_live_YOUR_API_KEY"
      }
    }
  }
}

7. Versioning & 90-Day Sunset Deprecation Policy

Our API follows strict semantic URI versioning (/api/v1). We guarantee backward compatibility for all stable endpoints.

Deprecation Notice: Any endpoint scheduled for retirement will emit standard HTTP Deprecation: true and Sunset: <HTTP-date> headers.

90-Day Grace Period: Deprecated endpoints are guaranteed to remain fully functional for a minimum of 90 calendar days following official notification before being retired.