API Reference

Complete reference for GitScribe's command-line interface and REST API.

CLI Commands

gitscribe init

Initialize GitScribe in a repository

gitscribe init [options]

# Options
  --style <style>        Commit style (conventional, angular, custom)
  --scope <scopes...>   List of allowed scopes
  --config <path>       Path to config file
  --force               Overwrite existing config
  --global              Initialize global config
  
# Examples
  gitscribe init
  gitscribe init --style angular --scope api,ui,docs
  gitscribe init --global

gitscribe generate

Generate a commit message for staged changes

gitscribe generate [options]

# Options
  --commit              Commit immediately after generation
  --amend              Amend previous commit
  --preview            Show preview without committing
  --output <file>      Write message to file
  --format <format>    Output format (text, json, markdown)
  --model <model>      Override AI model
  --hook               Run as Git hook
  --dry-run            Show what would be done
  
Examples:
  gitscribe generate
  gitscribe generate --commit
  gitscribe generate --preview --model gpt-4
  gitscribe generate --output commit.txt

gitscribe config

Configure GitScribe settings

gitscribe config [subcommand] [options]

Subcommands:
  set <key> <value>    Set configuration value
  get <key>            Get configuration value
  list                 List all settings
  reset                Reset to defaults
  edit                 Open config in editor
  
# Options
  --global             Use global config
  --system             Use system config
  --local              Use local config (default)
  
Examples:
  gitscribe config set commit.style conventional
  gitscribe config get ai.model
  gitscribe config list --global
  gitscribe config edit

gitscribe status

Show GitScribe status and info

gitscribe status [options]

# Options
  --verbose            Show detailed information
  --json               Output as JSON
  
Output includes:
  - Version information
  - Active configuration
  - AI model status
  - Usage statistics (Pro)
  - License status

gitscribe update

Update GitScribe to latest version

gitscribe update [options]

# Options
  --check              Check for updates only
  --version <version>  Update to specific version
  --force              Force update even if up-to-date
  --beta               Include beta versions
  
Examples:
  gitscribe update
  gitscribe update --check
  gitscribe update --version 2.1.0

gitscribe doctor

Run diagnostics on GitScribe installation.

gitscribe doctor [options]

# Options
  --fix                Attempt to fix issues
  --verbose            Show detailed diagnostics

Checks performed:

• Installation integrity
• Git integration
• Configuration validity
• Model availability
• API connectivity (Pro)

REST API

Authentication

All API requests require authentication via API key:

curl -H "Authorization: Bearer YOUR_API_KEY"   https://api.gitscri.be/v1/endpoint

Generate Commit Message

POST /v1/generate

Request Body:

{
  "diff": "string",          // Required: Git diff output
  "style": "conventional",   // Optional: Commit style
  "model": "gpt-4",         // Optional: AI model
  "options": {
    "scope": "api",         // Optional: Commit scope
    "type": "feat",         // Optional: Commit type
    "language": "en",       // Optional: Message language
    "maxLength": 72         // Optional: Max message length
  }
}

Response:

{
  "message": {
    "subject": "feat(api): add user authentication endpoints",
    "body": "- Implement JWT token generation
- Add login/logout routes",
    "footer": "Closes #123",
    "raw": "feat(api): add user authentication..."
  },
  "metadata": {
    "model": "gpt-4",
    "tokens": 150,
    "generated_at": "2024-01-15T10:30:00Z"
  }
}

Validate Commit Message

POST /v1/validate

Request Body:

{
  "message": "feat: add new feature",
  "style": "conventional",
  "rules": {
    "scopeRequired": true,
    "maxLength": 72
  }
}

Response:

{
  "valid": false,
  "errors": [
    {
      "type": "missing-scope",
      "message": "Scope is required for conventional commits"
    }
  ],
  "warnings": []
}

Get User Info

GET /v1/user

Response:

{
  "user": {
    "id": "user_123",
    "email": "dev@example.com",
    "plan": "pro",
    "team_id": "team_456"
  },
  "usage": {
    "commits_this_month": 1523,
    "commits_limit": 2000,
    "reset_date": "2024-02-01"
  }
}

Team Management

GET /v1/team
POST /v1/team/invite
DELETE /v1/team/members/:userId
PUT /v1/team/settings

SDK Reference

Node.js SDK

// Installation
npm install @gitscribe/sdk

// Usage
const { GitScribe } = require('@gitscribe/sdk');

const client = new GitScribe({
  apiKey: 'YOUR_API_KEY',
  model: 'gpt-4',
  baseUrl: 'https://api.gitscri.be' // Optional
});

// Generate message
const result = await client.generate({
  diff: gitDiff,
  style: 'conventional',
  options: {
    scope: 'api',
    language: 'en'
  }
});

// Validate message
const validation = await client.validate({
  message: 'feat: add feature',
  style: 'conventional'
});

// Get user info
const user = await client.getUser();

Python SDK

# Installation
pip install gitscribe

# Usage
from gitscribe import GitScribe

client = GitScribe(
    api_key="YOUR_API_KEY",
    model="gpt-4"
)

# Generate message
result = client.generate(
    diff=git_diff,
    style="conventional",
    options={
        "scope": "api",
        "language": "en"
    }
)

# Async support
import asyncio
from gitscribe import AsyncGitScribe

async def main():
    async with AsyncGitScribe(api_key="...") as client:
        result = await client.generate(diff=git_diff)
        
asyncio.run(main())

Go SDK

// Installation
go get github.com/gitscribe/gitscribe-go

// Usage
package main

import (
    "github.com/gitscribe/gitscribe-go"
)

func main() {
    client := gitscribe.NewClient("YOUR_API_KEY")
    
    result, err := client.Generate(&gitscribe.GenerateRequest{
        Diff:  gitDiff,
        Style: "conventional",
        Options: &gitscribe.Options{
            Scope:    "api",
            Language: "en",
        },
    })
}

Webhooks

Available Events

• commit.generated - Message generated
• commit.validated - Message validated
• team.member_added - Team member added
• team.member_removed - Team member removed
• usage.limit_reached - Usage limit reached

Webhook Payload

{
  "event": "commit.generated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "user_id": "user_123",
    "team_id": "team_456",
    "message": "feat: add new feature",
    "model": "gpt-4",
    "tokens": 150
  }
}

Webhook Security

Verify webhook signatures:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const expected = 'sha256=' + hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Rate Limits

Plan	Requests/min	Requests/hour	Requests/day
Free	10	100	1,000
Pro	60	1,000	10,000
Enterprise	Custom	Custom	Custom

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1642252800

Error Codes

Code	Message	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Access denied to resource
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error

Error Response Format

{
  "error": {
    "code": "invalid_diff",
    "message": "The provided diff is invalid or empty",
    "details": {
      "field": "diff",
      "requirement": "non-empty string"
    }
  }
}

Need help? Check our troubleshooting guide or join our Discord for support.