@git-ai-project/sdk

TypeScript client for the Git AI Public Analytics API.

Authentication

To use the API endpoints, you need an API key for your organization. For read access, use at least an admin read-only API key.

Pass the key as apiKey when creating the client. The client sends it in the x-api-key header.

import { createClient } from "@git-ai-project/sdk/client";

const client = createClient({
  apiKey: process.env.GIT_AI_API_KEY,
});

The default API base URL is https://usegitai.com. For local development, pass baseUrl:

const client = createClient({
  apiKey: process.env.GIT_AI_API_KEY,
  baseUrl: "http://localhost:4000",
});

Reading Data

The client exposes typed resources for repositories, contributors, sessions, events, and pull request analytics.

import { createClient } from "@git-ai-project/sdk/client";

const client = createClient({
  apiKey: process.env.GIT_AI_API_KEY,
});

const repo = "https://github.com/acme/widgets";

const prs = await client.repos.pullRequests(repo, {
  state: "merged",
  aiAided: true,
  limit: 10,
});

for (const pr of prs) {
  const detail = await pr.refresh();
  const sessions = await pr.sessions({ limit: 100 });

  console.log({
    number: detail.number,
    title: detail.title,
    percentAi: detail.percentAi,
    aiLines: detail.aiLines,
    humanLines: detail.humanLines,
    sessionCount: detail.sessionCount,
    estimatedCostUsd: detail.cost.totals.estimatedCostUsd,
    loadedSessions: sessions.items.length,
  });
}

Pagination

List methods return a Page<T>. Use items to read the current page and nextPage() to continue.

import { createClient, type Page, type Session } from "@git-ai-project/sdk/client";

const client = createClient({
  apiKey: process.env.GIT_AI_API_KEY,
});

let page: Page<Session> | null = await client.sessions.list({
  repositoryUrl: "https://github.com/acme/widgets",
  limit: 100,
});

while (page) {
  for (const session of page.items) {
    console.log(session.sessionId, session.agent, session.cost.totalTokens);
  }

  page = await page.nextPage();
}

Common Reads

await client.repos.list({ limit: 50 });
await client.contributors.list({ q: "alice", limit: 20 });
await client.sessions.list({ agent: "codex", limit: 100 });
await client.events.list({ eventKind: "tool_call", limit: 100 });

await client.repos.pullRequests("https://github.com/acme/widgets", {
  state: "open",
});

await client.repos.pullRequest("https://github.com/acme/widgets", 123);
await client.repos.pullRequestCommits("https://github.com/acme/widgets", 123);
await client.repos.pullRequestSessions("https://github.com/acme/widgets", 123);

Repository arguments can be a repository URL, a Repository returned by the client, or an object with { domain, org, repo }.

Errors

API failures throw GitAiApiError with the normalized API error code, HTTP status, request id, and optional details.

import { GitAiApiError, createClient } from "@git-ai-project/sdk/client";

try {
  const client = createClient({ apiKey: process.env.GIT_AI_API_KEY });
  await client.repos.list();
} catch (error) {
  if (error instanceof GitAiApiError) {
    console.error(error.code, error.status, error.requestId);
  }
  throw error;
}