Skip to main content

​
POST /api/generate

Generates a professional README file for a GitHub repository using AI. The endpoint analyzes the repository structure, files, and content to create comprehensive documentation.

​
Authentication

This endpoint requires authentication. Include valid Clerk authentication credentials in your request.

​
Request queueing

The endpoint implements a request queue system with a maximum of 20 concurrent requests. If the queue is full, the endpoint returns a 429 status code. Requests are processed sequentially to manage server load.

​
Request body

​
repoUrl
string
required
The GitHub repository URL to generate a README for. Must be a valid GitHub repository URL in the format: https://github.com/username/repository

​
Response

​
readme
string
The generated README content in Markdown format
​
inputTokens
number
The number of tokens used from the repository content analysis
​
outputTokens
number
The number of tokens in the generated README
​
warnings
array
Any warnings generated during repository analysis
​
limits
object
Repository size and token limits
​
max_file_size
string
Maximum file size that can be processed
​
max_total_size
string
Maximum total repository size
​
max_files
number
Maximum number of files that can be processed
​
max_directory_depth
number
Maximum directory depth that will be analyzed
​
max_input_tokens
number
Maximum input tokens allowed (default: 900,000)
​
queuePosition
number
Position in the request queue (only returned if request is queued)
​
message
string
Queue status message (only returned if request is queued)

​
Code examples

curl -X POST https://gitread.dev/api/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
    "repoUrl": "https://github.com/facebook/react"
  }'

​
Response examples

{
  "readme": "# React\n\nA JavaScript library for building user interfaces...\n",
  "inputTokens": 45000,
  "outputTokens": 850,
  "warnings": [],
  "limits": {
    "max_file_size": "10MB",
    "max_total_size": "100MB",
    "max_files": 10000,
    "max_directory_depth": 10,
    "max_input_tokens": 900000
  }
}

​
Error responses

​
error
string
Error message describing what went wrong

​
Status codes

​
400
Bad Request
Invalid repository URL, repository not found, or token limit exceededCommon errors:
  • Invalid repository URL. Please provide a valid GitHub repository URL in the format: https://github.com/username/repository
  • Repository content exceeds maximum token limit of 900,000 tokens (estimated X tokens)
​
401
Unauthorized
Authentication required. User must be signed in.Error message:
  • Authentication required. Please sign in to generate README files.
​
402
Payment Required
Insufficient credits to generate READMEError message:
  • Insufficient credits. Please purchase more credits to continue.
​
429
Too Many Requests
Server is at maximum capacity. The request queue is full.Error message:
  • 🚦 Server is busy. Please try again in a few moments.
​
500
Internal Server Error
Server error during README generationCommon errors:
  • OpenRouter API key is not configured. Please set OPENROUTER_API_KEY in your environment variables.
  • Error processing repository. Please check the URL and try again.
  • API rate limit exceeded. Please try again later.
  • Request timed out. Please try a smaller repository.

​
Credits

Each successful README generation consumes 1 credit from your account. Credits are deducted after the README is successfully generated. If generation fails, no credits are consumed.

​
Repository requirements

  • Must be a public GitHub repository
  • Repository URL must use HTTPS protocol
  • Maximum repository size and file count are enforced (see limits in response)
  • Maximum input tokens: 900,000 (approximately 675,000 words)

​
AI model

README files are generated using Google’s Gemini 2.5 Pro model via OpenRouter. The AI analyzes:
  • Repository structure and file tree
  • Source code content
  • Project metadata
  • Existing documentation
The generated README includes:
  • Project title and description
  • DeepWiki badge for interactive documentation
  • Installation instructions
  • Usage examples
  • API documentation (if applicable)
  • Contributing guidelines
  • License information

Build docs developers (and LLMs) love

Get started for freeTalk to us