Skip to main content
GitRead provides a RESTful API that allows you to programmatically generate README files, manage user credits, and access generation history. All API endpoints are built on Next.js API routes and require authentication via Clerk.

​
Base URL

The API is available at: 
https://gitread.dev/api
For local development: 
http://localhost:3000/api

​
Request format

All POST requests should include a Content-Type: application/json header and send data as JSON in the request body. 
{
  "repoUrl": "https://github.com/username/repository"
}

​
Response format

API responses are returned in JSON format with appropriate HTTP status codes.

​
Success response

{
  "readme": "# Project Name\n\nDescription...",
  "inputTokens": 45000,
  "outputTokens": 1200
}

​
Error response

{
  "error": "Error message describing what went wrong"
}

​
Available endpoints

​
README generation

POST /api/generate

Generate a professional README file for a GitHub repository using AI.

​
Credit management

GET /api/credits

Retrieve the authenticated user’s current credit balance.

POST /api/credits

Update the user’s credit balance (admin use).

​
README history

GET /api/readme-history

Fetch all READMEs generated by the authenticated user.

POST /api/readme-history

Save a generated README to the user’s history.

​
Payment processing

POST /api/create-checkout-session

Create a Stripe checkout session for purchasing credits.

POST /api/verify-payment

Verify a completed Stripe payment and add credits.

​
Error handling

The API uses standard HTTP status codes to indicate success or failure:
Status CodeDescription
200Request successful
400Bad request - invalid parameters or repository URL
401Unauthorized - authentication required
402Payment required - insufficient credits
429Too many requests - server is busy
500Server error - something went wrong
When you receive a 429 status code, the response may include a queuePosition field indicating your position in the generation queue.

​
Rate limiting

To ensure service stability, GitRead implements a request queue system:
  • Maximum queue size: 20 concurrent requests
  • Requests beyond this limit receive a 429 error
  • Queue position is returned when your request is queued
If the server is busy, wait a few moments before retrying your request.

​
Repository limits

When generating READMEs, repositories must meet these constraints:
  • Maximum input tokens: 900,000
  • Maximum file size: Varies by repository
  • Maximum total size: Varies by repository
  • Maximum directory depth: Limited
These limits are returned in the API response when exceeded, along with the specific constraint that was violated.

Build docs developers (and LLMs) love

Get started for freeTalk to us