API Overview

Copy MarkdownOpen

Base URL

https://api.coregit.dev/v1

Authentication

Include your API key in every request:

-H "x-api-key: cgk_live_YOUR_KEY"

Request ID

Every response includes an X-Request-Id header for debugging and support:

X-Request-Id: a1b2c3d4

Response Format

All responses return JSON. Successful responses use 2xx status codes. Errors include a human-readable error and a machine-readable code:

{
  "error": "Repository not found",
  "code": "NOT_FOUND"
}

Error Codes

Common Status Codes

Pagination

List endpoints support both offset and cursor-based pagination:

# Offset pagination
GET /v1/repos?limit=20&offset=0

# Cursor pagination (preferred for large datasets)
GET /v1/repos?limit=20&cursor=eyJ1cGRhdGVkX2F0Ijoi...

• limit — Number of items to return (varies by endpoint, typically max 100)
• offset — Number of items to skip (default: 0)
• cursor — Opaque token from next_cursor in the previous response

When next_cursor is null, there are no more results. Cursor pagination is more efficient than offset for large result sets.

Namespaces

Repositories can be organized into namespaces. Every repo-scoped endpoint supports two URL patterns:

/v1/repos/:slug/...                    # without namespace
/v1/repos/:namespace/:slug/...         # with namespace

For example, to list commits on a namespaced repository:

GET /v1/repos/alice/my-repo/commits

Namespaces follow the same validation as slugs: lowercase letters, numbers, and hyphens (1–100 chars, no consecutive hyphens).

When creating a repository, pass the optional namespace field:

{
  "slug": "my-repo",
  "namespace": "alice"
}

The namespace field appears in all repository responses (null when not set).

Public API (No Auth Required)

Public repositories can be read without authentication using org-scoped routes:

/v1/orgs/:orgSlug/repos                              — List public repos
/v1/orgs/:orgSlug/repos/:slug                        — Get public repo
/v1/orgs/:orgSlug/repos/:slug/refs                   — List refs
/v1/orgs/:orgSlug/repos/:slug/tree/:ref/*path        — Browse directory
/v1/orgs/:orgSlug/repos/:slug/blob/:ref/*path        — Read file
/v1/orgs/:orgSlug/repos/:slug/commits                — List commits
/v1/orgs/:orgSlug/repos/:slug/commits/:sha           — Get commit
/v1/orgs/:orgSlug/repos/:slug/diff?base=...&head=... — Diff

Namespaced variants are also available: /v1/orgs/:orgSlug/repos/:namespace/:slug/...

These endpoints only return data from repositories with visibility: "public". Write operations always require authentication.

Rate Limits

Per-key sliding window rate limiting applies to all authenticated requests:

• 600 requests / minute (burst)
• 15,000 requests / hour (sustained)

Rate limit headers are included on every response:

Monthly Quotas

• Free tier: 10,000 API calls / month, 5 repos, 1 GB storage
• Usage tier: Unlimited (metered billing)

Caching

Git objects are content-addressed and immutable. CoreGit returns caching headers on endpoints that serve immutable content:

Use If-None-Match to avoid re-downloading unchanged data. Responses return 304 Not Modified when the content hasn't changed.