apps/api/src/openapi.rs · flagon-io/g1t

API and MCP server in Rust; a public index at the API root6d ago

1

//! The OpenAPI document, generated from the same list the routes are.

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

2

//!

3

//! The docs site builds its API reference from a copy of this document,

4

//! `apps/docs/src/data/openapi.json`. A test keeps the copy current: run

5

//! `G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi` to rewrite it.

API and MCP server in Rust; a public index at the API root6d ago

6

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

7

use g1t_contracts::scopes::scope_for;

API and MCP server in Rust; a public index at the API root6d ago

8

use serde_json::{Map, Value, json};

9

10

use crate::operations::Op;

Merge rulesets: branch and tag rules, agent-first, enforced on push and merge7h ago

11

use crate::rules::RulesOp;

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

12

use crate::security::SecurityOp;

API and MCP server in Rust; a public index at the API root6d ago

13

use crate::rest::{ROUTES, Route};

14

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

15

/// The sections of the API reference: a name, what it covers, and its

16

/// operations in the order a reader meets them.

17

const SECTIONS: &[(&str, &str, &[Op])] = &[

18

(

19

"Accounts",

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

20

"Signing in from a tool, who a token acts as, and your email addresses.",

21

&[Op::Whoami, Op::ListEmails, Op::AddEmail, Op::RemoveEmail, Op::UpdateEmailSettings],

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

22

),

23

(

API: notifications over REST and MCP, with notifications scopes13h ago

24

"Notifications",

25

"Your inbox: a thread for each thing you were told about (an issue, a pull request, a workflow on a branch, a deployment), why you were told, and what you subscribe to and watch. Your own: personal tokens and sessions only.",

26

&[

27

Op::ListNotifications,

28

Op::MarkNotificationsRead,

29

Op::GetNotificationThread,

30

Op::MarkThreadRead,

31

Op::MarkThreadDone,

32

Op::SaveThread,

33

Op::SnoozeThread,

34

Op::GetThreadSubscription,

35

Op::SetThreadSubscription,

36

Op::DeleteThreadSubscription,

37

Op::GetRepoSubscription,

38

Op::SetRepoSubscription,

39

Op::DeleteRepoSubscription,

40

Op::ListWatchedRepos,

41

],

42

),

43

(

API: pinned projects over REST and MCP12h ago

44

"Pinned projects",

45

"The projects you keep at the top of a workspace's sidebar, in your order, up to eight a workspace. Your own: personal tokens and sessions only.",

46

&[Op::ListPinnedProjects, Op::PinProject, Op::UnpinProject, Op::ReorderPinnedProjects],

47

),

48

(

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

49

"Workspaces",

50

"A workspace owns repositories and is the first part of their address. People and agents work in workspaces.",

Merge branch 'worktree-agent-ad7c6d88d93adc817'8h ago

51

&[Op::GetWorkspace, Op::CreateWorkspace, Op::UpdateWorkspace, Op::DeleteWorkspace],

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

52

),

53

(

54

"Invites",

55

"While g1t is invite-only, every new account needs an invite. Your invites, and inviting people into a workspace by email.",

56

&[

57

Op::ListInvites,

58

Op::CreateInvite,

59

Op::RevokeInvite,

60

Op::ListWorkspaceInvites,

61

Op::InviteMember,

62

Op::RevokeWorkspaceInvite,

63

],

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

64

),

65

(

Usage, Billing settings and prepaid AI credit; fixes from the UX audit9h ago

66

"Billing",

Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens7h ago

67

"A workspace's usage, its budget, its AI credit, its invoices and its AI Gateway requests. Members read them; owners change the budget and buy credit, as people. g1t's agents never change billing.",

Usage, Billing settings and prepaid AI credit; fixes from the UX audit9h ago

68

&[

69

Op::GetUsage,

70

Op::GetBudget,

71

Op::SetBudget,

72

Op::GetAiCredit,

73

Op::BuyAiCredit,

74

Op::ListInvoices,

75

Op::GetBillingDetails,

Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens7h ago

76

Op::ListGatewayRequests,

Usage, Billing settings and prepaid AI credit; fixes from the UX audit9h ago

77

],

78

),

79

(

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

80

"Repositories",

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

81

"A repository, how it handles pull requests, and its timeline: renaming, archiving, moving and deleting it.",

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

82

&[

83

Op::ListRepos,

84

Op::CreateRepo,

85

Op::GetRepo,

86

Op::UpdateRepo,

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

87

Op::RenameRepo,

88

Op::RenameBranch,

89

Op::SetRepoVisibility,

90

Op::ArchiveRepo,

91

Op::UnarchiveRepo,

92

Op::TransferRepo,

93

Op::DeleteRepo,

94

Op::ListDeletedRepos,

95

Op::RestoreRepo,

96

Op::PurgeRepo,

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

97

Op::GetRepoSettings,

98

Op::UpdateRepoSettings,

Fast pages, required checks on the branch, self-hosted runners, honest incidents2d ago

99

Op::ListCheckNames,

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

100

Op::GetCodeownersErrors,

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

101

Op::ListEvents,

102

],

103

),

104

(

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

105

"Access",

106

"Who can do what in a repository: repository roles, people given a role on one repository (outside collaborators when they are not members), invitations, and a workspace's base permission.",

107

&[

108

Op::ListCollaborators,

109

Op::AddCollaborator,

110

Op::UpdateCollaborator,

111

Op::RemoveCollaborator,

112

Op::GetCollaboratorPermission,

113

Op::ListRepoInvitations,

114

Op::RevokeRepoInvitation,

115

Op::ListMyRepoInvitations,

116

Op::AcceptRepoInvitation,

117

Op::DeclineRepoInvitation,

118

Op::SetBasePermission,

119

Op::ListOutsideCollaborators,

120

],

121

),

122

(

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

123

"Teams",

124

"Groups of a workspace's members: given a role on repositories together, mentioned together as @workspace/team, and asked to review together. Any member may create a team; the workspace's owners and the team's maintainers manage it.",

125

&[

126

Op::ListTeams,

127

Op::CreateTeam,

128

Op::GetTeam,

129

Op::UpdateTeam,

130

Op::DeleteTeam,

131

Op::ListTeamMembers,

132

Op::SetTeamMember,

133

Op::RemoveTeamMember,

134

Op::ListChildTeams,

135

Op::ListTeamRepos,

136

Op::SetTeamRepo,

137

Op::RemoveTeamRepo,

138

Op::SetTeamReviewAssignment,

139

Op::ListUserTeams,

140

],

141

),

142

(

Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago

143

"Security",

144

"Secrets found in what is pushed and in a repository's history, and dependencies with known vulnerabilities: listing the alerts, and dismissing or reopening them.",

145

&[Op::ListSecurityAlerts, Op::DismissSecurityAlert, Op::ReopenSecurityAlert],

146

),

147

(

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

148

"Secret scanning",

149

"Secrets found in pushes and history, where each one is, pushing past push protection with a reason (and asking for approval when the workspace delegates bypasses), checking with a secret's issuer whether it still works, and custom patterns.",

150

&[

151

Op::Security(SecurityOp::ListSecretAlerts),

152

Op::Security(SecurityOp::GetSecretAlert),

153

Op::Security(SecurityOp::UpdateSecretAlert),

154

Op::Security(SecurityOp::ListSecretLocations),

155

Op::Security(SecurityOp::BypassPushProtection),

156

Op::Security(SecurityOp::CheckSecretValidity),

157

Op::Security(SecurityOp::ListBypassRequests),

158

Op::Security(SecurityOp::ReviewBypassRequest),

159

Op::Security(SecurityOp::ListCustomPatterns),

160

Op::Security(SecurityOp::CreateCustomPattern),

161

Op::Security(SecurityOp::UpdateCustomPattern),

162

Op::Security(SecurityOp::DeleteCustomPattern),

163

Op::Security(SecurityOp::DryRunCustomPattern),

164

],

165

),

166

(

167

"Code scanning",

168

"Results of static analysis tools, uploaded as SARIF: alerts on the default branch, the analyses that made them, uploads, and putting g1t on an alert to fix it.",

169

&[

170

Op::Security(SecurityOp::ListCodeAlerts),

171

Op::Security(SecurityOp::GetCodeAlert),

172

Op::Security(SecurityOp::UpdateCodeAlert),

173

Op::Security(SecurityOp::ListAnalyses),

174

Op::Security(SecurityOp::UploadSarif),

175

Op::Security(SecurityOp::GetSarifUpload),

176

Op::Security(SecurityOp::FixAlert),

177

],

178

),

179

(

180

"Supply chain",

181

"What a repository depends on: vulnerability alerts, the dependency graph, an SPDX SBOM of it, and comparing two commits' dependencies as dependency review does.",

182

&[

183

Op::Security(SecurityOp::ListVulnerabilityAlerts),

184

Op::Security(SecurityOp::GetVulnerabilityAlert),

185

Op::Security(SecurityOp::UpdateVulnerabilityAlert),

186

Op::Security(SecurityOp::GetDependencyGraph),

187

Op::Security(SecurityOp::GetSbom),

188

Op::Security(SecurityOp::CompareDependencies),

189

],

190

),

191

(

192

"Security settings",

193

"When pull request checks fail, dependency review's policy, delegated bypass and validity checks, and a workspace's security overview.",

194

&[

195

Op::Security(SecurityOp::GetSettings),

196

Op::Security(SecurityOp::UpdateSettings),

197

Op::Security(SecurityOp::GetWorkspaceSettings),

198

Op::Security(SecurityOp::UpdateWorkspaceSettings),

199

Op::Security(SecurityOp::GetOverview),

200

],

201

),

202

(

Merge rulesets: branch and tag rules, agent-first, enforced on push and merge7h ago

203

"Rules",

204

"Rulesets: what may happen to a repository's branches and tags and what a pull request needs before it merges, for a repository or across a workspace; the rules that hold for one branch; and how they judged each push and merge, with insights.",

205

&[

206

Op::Rules(RulesOp::ListRepoRulesets),

207

Op::Rules(RulesOp::CreateRepoRuleset),

208

Op::Rules(RulesOp::GetRepoRuleset),

209

Op::Rules(RulesOp::UpdateRepoRuleset),

210

Op::Rules(RulesOp::DeleteRepoRuleset),

211

Op::Rules(RulesOp::GetBranchRules),

212

Op::Rules(RulesOp::ListRuleEvaluations),

213

Op::Rules(RulesOp::ListWorkspaceRulesets),

214

Op::Rules(RulesOp::CreateWorkspaceRuleset),

215

Op::Rules(RulesOp::GetWorkspaceRuleset),

216

Op::Rules(RulesOp::UpdateWorkspaceRuleset),

217

Op::Rules(RulesOp::DeleteWorkspaceRuleset),

218

Op::Rules(RulesOp::ListWorkspaceRuleEvaluations),

219

],

220

),

221

(

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

222

"Issues",

223

"What should change in a repository, with labels and comments. Issues and pull requests share one sequence of numbers.",

224

&[

225

Op::ListIssues,

226

Op::CreateIssue,

227

Op::GetIssue,

228

Op::UpdateIssue,

229

Op::CloseIssue,

230

Op::ReopenIssue,

231

Op::AssignIssue,

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

232

Op::Delegate,

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

233

Op::AddComment,

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

234

Op::ListIssueLabels,

235

Op::AddIssueLabels,

236

Op::SetIssueLabels,

237

Op::RemoveIssueLabels,

238

],

239

),

240

(

241

"Labels and milestones",

242

"A repository's labels, which issues and pull requests carry by name, and its milestones, which gather them under a goal and a due date.",

243

&[

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

244

Op::ListLabels,

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

245

Op::CreateLabel,

246

Op::UpdateLabel,

247

Op::DeleteLabel,

248

Op::AddDefaultLabels,

249

Op::ListMilestones,

250

Op::CreateMilestone,

251

Op::GetMilestone,

252

Op::UpdateMilestone,

253

Op::DeleteMilestone,

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

254

],

255

),

256

(

257

"Plans",

258

"An outcome turned into the issues that would get there, with the order they must merge in.",

259

&[Op::PlanWork, Op::GetPlan, Op::ApplyPlan],

260

),

261

(

262

"Pull requests",

263

"A proposed change in its own fork or on a branch. Several can be made for one issue; the one merged resolves it.",

264

&[

265

Op::ListPullRequests,

266

Op::CreatePullRequest,

267

Op::GetPullRequest,

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

268

Op::UpdatePullRequest,

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

269

Op::GetPullRequestChanges,

270

Op::MarkPullRequestReady,

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

271

Op::RequestReviewers,

272

Op::RemoveRequestedReviewers,

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

273

Op::ReviewPullRequest,

274

Op::MergePullRequest,

275

Op::ClosePullRequest,

276

Op::GetMergeQueue,

277

Op::MessageAgent,

278

Op::AnswerMessage,

279

Op::TakeMessages,

280

],

281

),

282

(

283

"Sessions",

284

"The record of how a pull request was made: prompts, reasoning and the tools that ran.",

285

&[Op::ReadSession, Op::RecordSession],

286

),

287

(

Agents and memory, checks and conflicts, profiles, slug renames, custom domains3d ago

288

"Memory",

289

"What agents and people learned that the next agent should know, for one project or across a workspace. Members and g1t's agents only; never a secret.",

290

&[Op::Remember, Op::Recall],

291

),

292

(

Search across all of g1t, Explore, and a command palette3d ago

293

"Search",

294

"One search across all of g1t: repositories, code, issues, pull requests, people and workspaces. Public content for everyone, and private content in workspaces you belong to.",

295

&[Op::Search],

296

),

297

(

Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API3d ago

298

"Context",

299

"A workspace's context hub: a catalog of what it builds and runs, built from its repositories, deployments and integrations, and one search across the catalog, docs, issues, pull requests and memory.",

300

&[Op::SearchContext, Op::GetEntity],

301

),

302

(

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

303

"Actions",

304

"GitHub Actions workflows in .g1t/workflows, their runs, and their jobs' logs.",

305

&[

306

Op::ListWorkflows,

307

Op::ListWorkflowRuns,

308

Op::GetWorkflowRun,

309

Op::GetJobLogs,

310

Op::DispatchWorkflow,

311

Op::CancelWorkflowRun,

312

Op::RerunWorkflowRun,

313

Op::UpdateWorkflow,

314

],

315

),

316

(

317

"Secrets and variables",

318

"Values that workflows and deployments read, per repository or for a whole workspace, with a row per environment.",

319

&[

320

Op::ListActionsSecrets,

321

Op::SetActionsSecret,

322

Op::DeleteActionsSecret,

323

Op::ListActionsVariables,

324

Op::SetActionsVariable,

325

Op::DeleteActionsVariable,

326

],

327

),

328

(

Fast pages, required checks on the branch, self-hosted runners, honest incidents2d ago

329

"Runners",

330

"Self-hosted runners: your own machines, which run your workflow jobs (and, if you choose, your agents' work) for $0 of g1t compute. They register with a short-lived token and only ever connect out.",

331

&[

332

Op::ListRunners,

333

Op::CreateRunnerRegistrationToken,

334

Op::RemoveRunner,

335

Op::ListRunnerGroups,

336

Op::CreateRunnerGroup,

337

Op::UpdateRunnerGroup,

338

Op::DeleteRunnerGroup,

339

Op::GetRunnerSettings,

340

Op::UpdateRunnerSettings,

341

],

342

),

343

(

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

344

"Webhooks",

345

"Signed HTTPS requests sent to your own address as things happen, for a repository or a whole workspace.",

346

&[

347

Op::ListWebhooks,

348

Op::CreateWebhook,

349

Op::UpdateWebhook,

350

Op::DeleteWebhook,

351

Op::PingWebhook,

352

Op::ListWebhookDeliveries,

353

Op::RedeliverWebhook,

354

],

355

),

356

(

357

"Integrations",

358

"A workspace's connections to outside systems: model providers, alert sources and issue trackers.",

359

&[

360

Op::ListIntegrations,

361

Op::ConnectIntegration,

362

Op::DisconnectIntegration,

363

Op::TestIntegration,

364

Op::GetModelRoutes,

365

Op::SetModelRoutes,

366

Op::GetContext,

367

Op::ImportIssue,

368

],

369

),

370

];

371

API and MCP server in Rust; a public index at the API root6d ago

372

/// The section of the API reference an operation is listed under.

373

fn tag(op: Op) -> &'static str {

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

374

SECTIONS

API and MCP server in Rust; a public index at the API root6d ago

375

.iter()

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

376

.find(|(_, _, ops)| ops.contains(&op))

377

.map_or("Repositories", |(name, _, _)| name)

378

}

379

380

/// What an operation's page is called, as a short sentence.

381

fn title(op: Op) -> &'static str {

382

match op {

383

Op::Whoami => "Get the current user",

Merge branch 'worktree-agent-ad7c6d88d93adc817'8h ago

384

Op::GetWorkspace => "Get a workspace",

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

385

Op::CreateWorkspace => "Create a workspace",

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

386

Op::DeleteWorkspace => "Delete a workspace",

Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago

387

Op::UpdateWorkspace => "Update a workspace",

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

388

Op::ListEmails => "List your email addresses",

389

Op::AddEmail => "Add an email address",

390

Op::RemoveEmail => "Remove an email address",

391

Op::UpdateEmailSettings => "Change your email settings",

392

Op::ListInvites => "List your invites",

393

Op::CreateInvite => "Create an invite",

394

Op::RevokeInvite => "Revoke an invite",

395

Op::ListWorkspaceInvites => "List a workspace's invites",

396

Op::InviteMember => "Invite someone to a workspace",

397

Op::RevokeWorkspaceInvite => "Revoke a workspace's invite",

398

Op::TransferRepo => "Transfer a repository",

399

Op::RenameRepo => "Rename a repository",

400

Op::RenameBranch => "Rename a branch",

401

Op::ArchiveRepo => "Archive a repository",

402

Op::UnarchiveRepo => "Unarchive a repository",

403

Op::SetRepoVisibility => "Change a repository's visibility",

404

Op::DeleteRepo => "Delete a repository",

405

Op::ListDeletedRepos => "List recently deleted repositories",

406

Op::RestoreRepo => "Restore a deleted repository",

407

Op::PurgeRepo => "Purge a deleted repository",

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

408

Op::ListRepos => "List repositories",

409

Op::GetRepo => "Get a repository",

410

Op::CreateRepo => "Create a repository",

411

Op::UpdateRepo => "Update a repository",

412

Op::GetRepoSettings => "Get repository settings",

413

Op::UpdateRepoSettings => "Update repository settings",

Fast pages, required checks on the branch, self-hosted runners, honest incidents2d ago

414

Op::ListCheckNames => "List check names",

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

415

Op::GetMergeQueue => "Get the merge queue",

416

Op::MessageAgent => "Message an agent",

417

Op::AnswerMessage => "Answer a message",

418

Op::TakeMessages => "Take new messages",

Agents and memory, checks and conflicts, profiles, slug renames, custom domains3d ago

419

Op::Remember => "Remember something",

420

Op::Recall => "Recall memory",

Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API3d ago

421

Op::SearchContext => "Search the context hub",

422

Op::GetEntity => "Get a catalog entry",

Search across all of g1t, Explore, and a command palette3d ago

423

Op::Search => "Search g1t",

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

424

Op::ListIssues => "List issues",

425

Op::GetIssue => "Get an issue",

426

Op::CreateIssue => "Create an issue",

427

Op::UpdateIssue => "Update an issue",

428

Op::CloseIssue => "Close an issue",

429

Op::ReopenIssue => "Reopen an issue",

g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent2d ago

430

Op::AssignIssue => "Assign an issue to g1t",

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

431

Op::Delegate => "Put an agent on it",

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

432

Op::PlanWork => "Plan work",

433

Op::GetPlan => "Get a plan",

434

Op::ApplyPlan => "Apply a plan",

435

Op::ListLabels => "List labels",

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

436

Op::CreateLabel => "Create a label",

437

Op::UpdateLabel => "Update a label",

438

Op::DeleteLabel => "Delete a label",

439

Op::AddDefaultLabels => "Add the default labels",

440

Op::ListIssueLabels => "List an issue's labels",

441

Op::AddIssueLabels => "Add labels to an issue",

442

Op::SetIssueLabels => "Set an issue's labels",

443

Op::RemoveIssueLabels => "Remove labels from an issue",

444

Op::ListMilestones => "List milestones",

445

Op::GetMilestone => "Get a milestone",

446

Op::CreateMilestone => "Create a milestone",

447

Op::UpdateMilestone => "Update a milestone",

448

Op::DeleteMilestone => "Delete a milestone",

449

Op::UpdatePullRequest => "Update a pull request",

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

450

Op::AddComment => "Add a comment",

451

Op::ReviewPullRequest => "Review a pull request",

452

Op::ListPullRequests => "List pull requests",

453

Op::GetPullRequest => "Get a pull request",

454

Op::CreatePullRequest => "Create a pull request",

455

Op::RecordSession => "Record session entries",

456

Op::ReadSession => "Read a session",

457

Op::MarkPullRequestReady => "Mark a pull request ready",

458

Op::ClosePullRequest => "Close a pull request",

459

Op::GetPullRequestChanges => "Get a pull request's changes",

460

Op::MergePullRequest => "Merge a pull request",

461

Op::ListEvents => "List repository events",

462

Op::ListIntegrations => "List integrations",

463

Op::ConnectIntegration => "Connect an integration",

464

Op::DisconnectIntegration => "Disconnect an integration",

465

Op::TestIntegration => "Test an integration",

466

Op::GetContext => "Look up a ticket",

467

Op::ImportIssue => "Import an issue",

468

Op::GetModelRoutes => "Get model routes",

469

Op::SetModelRoutes => "Set model routes",

470

Op::ListWebhooks => "List webhooks",

471

Op::CreateWebhook => "Create a webhook",

472

Op::UpdateWebhook => "Update a webhook",

473

Op::DeleteWebhook => "Delete a webhook",

474

Op::PingWebhook => "Ping a webhook",

475

Op::ListWebhookDeliveries => "List webhook deliveries",

476

Op::RedeliverWebhook => "Redeliver a webhook delivery",

477

Op::ListWorkflows => "List workflows",

478

Op::ListWorkflowRuns => "List workflow runs",

479

Op::GetWorkflowRun => "Get a workflow run",

480

Op::GetJobLogs => "Get a job's log",

481

Op::DispatchWorkflow => "Run a workflow",

482

Op::CancelWorkflowRun => "Cancel a workflow run",

483

Op::RerunWorkflowRun => "Re-run a workflow run",

484

Op::UpdateWorkflow => "Turn a workflow on or off",

485

Op::ListActionsSecrets => "List secrets",

486

Op::SetActionsSecret => "Set a secret",

487

Op::DeleteActionsSecret => "Delete a secret",

488

Op::ListActionsVariables => "List variables",

489

Op::SetActionsVariable => "Set a variable",

490

Op::DeleteActionsVariable => "Delete a variable",

Fast pages, required checks on the branch, self-hosted runners, honest incidents2d ago

491

Op::ListRunners => "List self-hosted runners",

492

Op::ListRunnerGroups => "List runner groups",

493

Op::GetRunnerSettings => "Get runner settings",

494

Op::CreateRunnerRegistrationToken => "Create a runner registration token",

495

Op::RemoveRunner => "Remove a self-hosted runner",

496

Op::CreateRunnerGroup => "Create a runner group",

497

Op::UpdateRunnerGroup => "Change a runner group",

498

Op::DeleteRunnerGroup => "Delete a runner group",

499

Op::UpdateRunnerSettings => "Change runner settings",

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

500

Op::ListCollaborators => "List who has access",

501

Op::AddCollaborator => "Add a collaborator",

502

Op::UpdateCollaborator => "Change a collaborator's role",

503

Op::RemoveCollaborator => "Remove a collaborator",

504

Op::GetCollaboratorPermission => "Get someone's permission",

505

Op::ListRepoInvitations => "List a repository's invitations",

506

Op::RevokeRepoInvitation => "Revoke a repository invitation",

507

Op::ListMyRepoInvitations => "List your repository invitations",

508

Op::AcceptRepoInvitation => "Accept a repository invitation",

509

Op::DeclineRepoInvitation => "Decline a repository invitation",

510

Op::SetBasePermission => "Set the base permission",

511

Op::ListOutsideCollaborators => "List outside collaborators",

Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago

512

Op::ListSecurityAlerts => "List security alerts",

513

Op::DismissSecurityAlert => "Dismiss a security alert",

514

Op::ReopenSecurityAlert => "Reopen a security alert",

API: notifications over REST and MCP, with notifications scopes13h ago

515

Op::ListNotifications => "List notifications",

516

Op::MarkNotificationsRead => "Mark notifications read",

517

Op::GetNotificationThread => "Get a thread",

518

Op::MarkThreadRead => "Mark a thread read",

519

Op::MarkThreadDone => "Mark a thread done",

520

Op::SaveThread => "Save a thread",

521

Op::SnoozeThread => "Snooze a thread",

522

Op::GetThreadSubscription => "Get a thread subscription",

523

Op::SetThreadSubscription => "Set a thread subscription",

524

Op::DeleteThreadSubscription => "Unsubscribe from a thread",

525

Op::GetRepoSubscription => "Get how you watch a repository",

526

Op::SetRepoSubscription => "Watch a repository",

527

Op::DeleteRepoSubscription => "Stop watching a repository",

528

Op::ListWatchedRepos => "List repositories you watch",

API: pinned projects over REST and MCP12h ago

529

Op::ListPinnedProjects => "List your pinned projects",

Usage, Billing settings and prepaid AI credit; fixes from the UX audit9h ago

530

Op::GetUsage => "Get a workspace's usage",

531

Op::GetBudget => "Get a workspace's budget",

532

Op::SetBudget => "Change a workspace's budget",

533

Op::GetAiCredit => "Get a workspace's AI credit",

534

Op::BuyAiCredit => "Buy AI credit",

535

Op::ListInvoices => "List a workspace's invoices",

536

Op::GetBillingDetails => "Get a workspace's billing details",

Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens7h ago

537

Op::ListGatewayRequests => "List a workspace's AI Gateway requests",

API: pinned projects over REST and MCP12h ago

538

Op::PinProject => "Pin a project",

539

Op::UnpinProject => "Unpin a project",

540

Op::ReorderPinnedProjects => "Reorder your pinned projects",

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

541

Op::ListTeams => "List teams",

542

Op::GetTeam => "Get a team",

543

Op::CreateTeam => "Create a team",

544

Op::UpdateTeam => "Update a team",

545

Op::DeleteTeam => "Delete a team",

546

Op::ListTeamMembers => "List a team's members",

547

Op::SetTeamMember => "Add or change a team member",

548

Op::RemoveTeamMember => "Remove a team member",

549

Op::ListChildTeams => "List child teams",

550

Op::ListTeamRepos => "List a team's repositories",

551

Op::SetTeamRepo => "Give a team a role on a repository",

552

Op::RemoveTeamRepo => "Remove a team from a repository",

553

Op::SetTeamReviewAssignment => "Set a team's review assignment",

554

Op::ListUserTeams => "List someone's teams",

555

Op::RequestReviewers => "Request reviewers",

556

Op::RemoveRequestedReviewers => "Remove requested reviewers",

557

Op::GetCodeownersErrors => "List CODEOWNERS errors",

558

Op::Security(op) => op.title(),

Merge rulesets: branch and tag rules, agent-first, enforced on push and merge7h ago

559

Op::Rules(op) => op.title(),

API and MCP server in Rust; a public index at the API root6d ago

560

}

561

}

562

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

563

/// Why an operation can be refused with `402 payment_required`, if it

564

/// can: the ones that start an agent, when the workspace has no credit,

565

/// and the ones that make a repository private in a workspace, when a free

566

/// workspace's private storage has no room for it.

567

fn may_need_payment(op: Op) -> Option<&'static str> {

568

match op {

569

Op::AssignIssue | Op::PlanWork | Op::ApplyPlan => Some("The workspace has no agent credit."),

570

Op::UpdateRepo | Op::SetRepoVisibility | Op::TransferRepo => Some(

571

"A free workspace's private storage has no room for this private repository.",

572

),

573

_ => None,

574

}

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

575

}

576

577

/// What the reference says beyond each operation's own description, keyed

578

/// by operation id, written by hand from what the services return: `notes`

579

/// (Markdown, added to the description) and example `params` (path),

580

/// `query`, `request` (body) and `response`.

581

const REFERENCE: &str = include_str!("reference.json");

582

583

fn examples() -> Map<String, Value> {

584

match serde_json::from_str(REFERENCE) {

585

Ok(Value::Object(examples)) => examples,

586

_ => Map::new(),

API and MCP server in Rust; a public index at the API root6d ago

587

}

588

}

589

Agents as a team: lifecycle, merge queue, billing and a new shell5d ago

590

/// `/repos/:owner/:name` as OpenAPI writes it: `/repos/{owner}/{name}`.

API and MCP server in Rust; a public index at the API root6d ago

591

fn openapi_path(route: &Route) -> String {

592

route

593

.path

594

.split('/')

595

.map(|segment| match segment.strip_prefix(':') {

596

Some(name) => format!("{{{name}}}"),

597

None => segment.to_owned(),

598

})

599

.collect::<Vec<_>>()

600

.join("/")

601

}

602

603

fn error_response(description: &str) -> Value {

604

json!({

605

"description": description,

606

"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } },

607

})

608

}

609

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

610

/// A parameter in the path or the query, described by the operation's

611

/// input schema where it has the same name.

612

fn parameter(name: &str, place: &str, required: bool, schema: Option<&Value>) -> Value {

613

let mut schema = schema.cloned().unwrap_or_else(|| json!({ "type": "string" }));

614

let description = match name {

615

"owner" => Some(Value::from("The workspace that owns the repository.")),

616

"name" => Some(Value::from("The repository's name.")),

617

_ => schema.as_object_mut().and_then(|schema| schema.remove("description")),

618

};

619

let mut parameter = json!({

620

"name": name,

621

"in": place,

622

"required": required,

623

"schema": schema,

624

});

625

if let Some(description) = description {

626

parameter["description"] = description;

627

}

628

parameter

629

}

630

631

/// The operation id of a route. An operation reached at a workspace's

632

/// address as well as a repository's is documented once for each, with its

633

/// own id; GitHub's alternative addresses for one operation keep GitHub's

634

/// names.

635

fn operation_id(route: &Route) -> String {

636

let op = route.op;

637

let base = match (route.method, route.path.rsplit('/').next().unwrap_or_default()) {

638

("PUT", "enable") => "enable_workflow".to_owned(),

639

("PUT", "disable") => "disable_workflow".to_owned(),

640

("POST", "rerun-failed-jobs") => "rerun_failed_jobs".to_owned(),

641

("PATCH", ":setting") => "update_actions_variable".to_owned(),

642

("GET", "runs") if route.path.contains("/workflows/:workflow/") => "list_runs_of_workflow".to_owned(),

API: notifications over REST and MCP, with notifications scopes13h ago

643

// One repository's notifications, and an issue's subscription by

644

// its number rather than a thread's id.

645

(_, "notifications") if route.path.starts_with("/repos/") => match op {

646

Op::ListNotifications => "list_repo_notifications".to_owned(),

647

_ => "mark_repo_notifications_read".to_owned(),

648

},

649

(method, "subscription") if route.path.contains("/issues/:number/") => match method {

650

"GET" => "get_issue_subscription".to_owned(),

651

"PUT" => "set_issue_subscription".to_owned(),

652

_ => "delete_issue_subscription".to_owned(),

653

},

Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar9h ago

654

// One label off an issue, by its name in the path.

655

("DELETE", ":label") if route.path.contains("/issues/:number/") => "remove_issue_label".to_owned(),

API: notifications over REST and MCP, with notifications scopes13h ago

656

("DELETE", "saved") => "unsave_thread".to_owned(),

657

("DELETE", "snooze") => "unsnooze_thread".to_owned(),

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

658

_ => op.name().to_owned(),

659

};

660

if route.path.starts_with("/workspaces/") && ROUTES.iter().any(|other| other.op == op && other.path.starts_with("/repos/")) {

661

format!("{base}_for_workspace")

662

} else {

663

base

664

}

665

}

666

667

/// The summary of a route: its operation's title, or for one of GitHub's

668

/// alternative addresses, what that address does.

669

fn summary(route: &Route, id: &str) -> String {

670

let base = match id.trim_end_matches("_for_workspace") {

671

"enable_workflow" => "Turn a workflow on",

672

"disable_workflow" => "Turn a workflow off",

673

"rerun_failed_jobs" => "Re-run failed jobs",

674

"update_actions_variable" => "Update a variable",

675

"list_runs_of_workflow" => "List a workflow's runs",

API: notifications over REST and MCP, with notifications scopes13h ago

676

"list_repo_notifications" => "List a repository's notifications",

677

"mark_repo_notifications_read" => "Mark a repository's notifications read",

678

"get_issue_subscription" => "Get your subscription to an issue",

679

"set_issue_subscription" => "Subscribe to an issue",

680

"delete_issue_subscription" => "Unsubscribe from an issue",

681

"unsave_thread" => "Unsave a thread",

682

"unsnooze_thread" => "Bring a snoozed thread back",

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

683

_ => title(route.op),

684

};

685

if id.ends_with("_for_workspace") {

686

format!("{base} for a workspace")

687

} else {

688

base.to_owned()

689

}

690

}

691

API and MCP server in Rust; a public index at the API root6d ago

692

fn operation(route: &Route) -> Value {

693

let op = route.op;

694

let path_params: Vec<&str> = route.params().collect();

695

// `owner` and `name` in the path stand for the operation's `repo` input.

696

let covered = |name: &str| name == "repo" || path_params.contains(&name);

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

697

let all_properties = op.properties();

698

let mut properties = all_properties.clone();

API and MCP server in Rust; a public index at the API root6d ago

699

properties.retain(|name, _| !covered(name));

700

let required: Vec<String> = op

701

.required()

702

.into_iter()

703

.filter(|name| !covered(name))

704

.collect();

705

706

let mut parameters: Vec<Value> = path_params

707

.iter()

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

708

.map(|name| parameter(name, "path", true, all_properties.get(*name)))

API and MCP server in Rust; a public index at the API root6d ago

709

.collect();

710

let mut body = Value::Null;

711

if route.method == "GET" {

712

for (name, key) in route.query {

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

713

parameters.push(parameter(

714

name,

715

"query",

716

required.iter().any(|required| required == key),

717

properties.get(*key),

718

));

API and MCP server in Rust; a public index at the API root6d ago

719

}

720

} else if !properties.is_empty() {

721

let mut schema = json!({ "type": "object", "properties": properties });

722

if !required.is_empty() {

723

schema["required"] = json!(required);

724

}

725

body = json!({

726

"required": !required.is_empty(),

727

"content": { "application/json": { "schema": schema } },

728

});

729

}

730

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

731

let id = operation_id(route);

732

let mut responses = Map::new();

733

responses.insert(

734

"200".into(),

735

json!({

736

"description": "Success.",

737

"content": { "application/json": { "schema": {} } },

738

}),

739

);

740

responses.insert(

741

"401".into(),

742

error_response("A token is required, or the one sent is not valid."),

743

);

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look2d ago

744

if let Some(reason) = may_need_payment(op) {

745

responses.insert("402".into(), error_response(reason));

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

746

}

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

747

responses.insert(

748

"403".into(),

749

error_response("Signed in, but not allowed to do this: the role you have is not enough, or the token lacks the scope it needs, which `needed_scope` names."),

750

);

Search across all of g1t, Explore, and a command palette3d ago

751

if !matches!(op, Op::Whoami | Op::ListRepos | Op::Search) {

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

752

responses.insert("404".into(), error_response("It does not exist, or you cannot see it."));

753

}

754

if route.method != "GET" {

755

responses.insert(

756

"409".into(),

757

error_response("The request conflicts with the current state."),

758

);

759

}

760

if op != Op::Whoami {

761

responses.insert("422".into(), error_response("The input is not valid."));

762

}

763

// Public data can be read without a token; everything else needs one.

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

764

let scope: Vec<&str> = scope_for(op.name()).map(|scope| scope.as_str()).into_iter().collect();

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

765

let security = if op.needs_user() {

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

766

json!([{ "token": scope }])

Webhooks: every event, to your own addresses, signed and retried5d ago

767

} else {

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

768

json!([{ "token": scope }, {}])

Webhooks: every event, to your own addresses, signed and retried5d ago

769

};

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

770

let (tool, action) = crate::tools::TOOLS

771

.iter()

772

.find_map(|tool| {

773

tool.actions

774

.iter()

775

.find(|action| action.op == op)

776

.map(|action| (tool.name, action.name))

777

})

778

.unwrap_or_default();

API and MCP server in Rust; a public index at the API root6d ago

779

let mut described = json!({

Webhooks: every event, to your own addresses, signed and retried5d ago

780

"operationId": id,

API and MCP server in Rust; a public index at the API root6d ago

781

"tags": [tag(op)],

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

782

"summary": summary(route, &id),

API and MCP server in Rust; a public index at the API root6d ago

783

"description": op.description(),

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

784

"x-operation": op.name(),

785

"x-mcp-tool": tool,

786

"x-mcp-action": action,

787

"x-scope": scope.first().copied(),

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

788

"security": security,

API and MCP server in Rust; a public index at the API root6d ago

789

"parameters": parameters,

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

790

"responses": responses,

API and MCP server in Rust; a public index at the API root6d ago

791

});

792

if !body.is_null() {

793

described["requestBody"] = body;

794

}

795

described

796

}

797

798

/// Entries for device sign-in, which is not an operation.

799

fn onboarding() -> Map<String, Value> {

800

let paths = json!({

Agents as a team: lifecycle, merge queue, billing and a new shell5d ago

801

"/device/code": {

API and MCP server in Rust; a public index at the API root6d ago

802

"post": {

803

"operationId": "device_code",

804

"tags": ["Accounts"],

805

"summary": "Start signing in",

Agents as a team: lifecycle, merge queue, billing and a new shell5d ago

806

"description": "Begins a device sign-in. Show the person `verification_uri_complete` and have them open it in a browser, where they sign in or register and approve the code. Then poll `/device/token`.",

API and MCP server in Rust; a public index at the API root6d ago

807

"security": [],

808

"requestBody": {

809

"content": { "application/json": { "schema": {

810

"type": "object",

811

"properties": {

812

"client_name": {

813

"type": "string",

814

"description": "What is asking, shown to the person approving. For example, Claude Code.",

815

},

816

},

817

} } },

818

},

819

"responses": { "200": {

820

"description": "The codes for this sign-in.",

821

"content": { "application/json": { "schema": {

822

"type": "object",

823

"properties": {

Agents as a team: lifecycle, merge queue, billing and a new shell5d ago

824

"device_code": { "type": "string", "description": "Secret. Send it to /device/token." },

API and MCP server in Rust; a public index at the API root6d ago

825

"user_code": { "type": "string", "description": "Shown to the person, like WDJB-MJHT." },

826

"verification_uri": { "type": "string" },

827

"verification_uri_complete": {

828

"type": "string",

829

"description": "The link to give the person; it carries the code.",

830

},

831

"expires_in": { "type": "integer", "description": "Seconds until the codes expire." },

832

"interval": { "type": "integer", "description": "Seconds to wait between polls." },

833

},

834

} } },

835

} },

836

},

837

},

Agents as a team: lifecycle, merge queue, billing and a new shell5d ago

838

"/device/token": {

API and MCP server in Rust; a public index at the API root6d ago

839

"post": {

840

"operationId": "device_token",

841

"tags": ["Accounts"],

842

"summary": "Finish signing in",

843

"description": "Asks whether the person has approved. Poll no faster than the interval. The token is returned once.",

844

"security": [],

845

"requestBody": {

846

"required": true,

847

"content": { "application/json": { "schema": {

848

"type": "object",

849

"required": ["device_code"],

850

"properties": { "device_code": { "type": "string" } },

851

} } },

852

},

853

"responses": { "200": {

854

"description": "The state of the sign-in.",

855

"content": { "application/json": { "schema": {

856

"type": "object",

857

"required": ["status"],

858

"properties": {

859

"status": { "type": "string", "enum": ["pending", "approved", "denied", "expired"] },

860

"token": { "type": "string", "description": "Present when approved." },

861

"username": { "type": "string" },

862

"verified": {

863

"type": "boolean",

864

"description": "Whether the account's email is confirmed.",

865

},

866

},

867

} } },

868

} },

869

},

870

},

871

});

872

match paths {

873

Value::Object(paths) => paths,

874

_ => Map::new(),

875

}

876

}

877

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

878

879

/// Puts each operation's examples, where it has them, into its request

880

/// and response. Path and query values go under `x-example-params` and

881

/// `x-example-query`, which tools that build a request can use.

882

fn attach_examples(paths: &mut Map<String, Value>) {

883

let examples = examples();

884

for methods in paths.values_mut() {

885

let Some(methods) = methods.as_object_mut() else { continue };

886

for operation in methods.values_mut() {

887

let id = operation["operationId"].as_str().unwrap_or_default().to_owned();

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

888

let name = operation["x-operation"].as_str().unwrap_or_default().to_owned();

889

let Some(example) = examples.get(&id).or_else(|| examples.get(&name)) else {

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

890

continue;

891

};

892

if let Some(notes) = example.get("notes").and_then(Value::as_str) {

893

let description = operation["description"].as_str().unwrap_or_default();

894

operation["description"] = json!(format!("{description}\n\n{notes}"));

895

}

896

if let Some(response) = example.get("response") {

897

let content = &mut operation["responses"]["200"]["content"]["application/json"];

898

if content.is_object() {

899

content["example"] = response.clone();

900

}

901

}

902

if let Some(request) = example.get("request") {

903

let content = &mut operation["requestBody"]["content"]["application/json"];

904

if content.is_object() {

905

content["example"] = request.clone();

906

}

907

}

908

for (key, extension) in [("params", "x-example-params"), ("query", "x-example-query")] {

909

if let Some(values) = example.get(key) {

910

operation[extension] = values.clone();

911

}

912

}

913

}

914

}

915

}

916

API and MCP server in Rust; a public index at the API root6d ago

917

pub fn document() -> Value {

918

let mut paths = onboarding();

919

for route in ROUTES {

920

let entry = paths

921

.entry(openapi_path(route))

922

.or_insert_with(|| json!({}));

923

entry[route.method.to_lowercase()] = operation(route);

924

}

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

925

attach_examples(&mut paths);

926

let tags: Vec<Value> = SECTIONS

927

.iter()

928

.map(|(name, description, ops)| {

929

json!({

930

"name": name,

931

"description": description,

932

// The section's operations in reading order, by MCP tool name.

933

"x-tools": ops.iter().map(|op| op.name()).collect::<Vec<_>>(),

934

})

935

})

936

.collect();

937

let codes = ["unauthenticated", "payment_required", "forbidden", "not_found", "conflict", "invalid"];

API and MCP server in Rust; a public index at the API root6d ago

938

json!({

939

"openapi": "3.1.0",

940

"info": {

941

"title": "g1t API",

942

"version": "1",

Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API3d ago

943

"description": "The REST API for g1t, a git forge built for agents. The same operations are available to agents as MCP tools at https://mcp.g1t.sh. Every name in a request or response body is `snake_case`; names you chose, such as a workflow's inputs or a secret's name, are returned as you wrote them.",

API and MCP server in Rust; a public index at the API root6d ago

944

"license": { "name": "MIT", "identifier": "MIT" },

945

},

946

"servers": [{ "url": "https://api.g1t.sh" }],

947

"security": [{ "token": [] }, {}],

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

948

"tags": tags,

API and MCP server in Rust; a public index at the API root6d ago

949

"paths": paths,

950

"components": {

951

"securitySchemes": {

952

"token": {

953

"type": "http",

954

"scheme": "bearer",

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

955

"description": "An access token, `g1t_…`. Public data needs none. Each operation names the scope a token needs for it; see https://docs.g1t.sh/guides/authentication/#scopes.",

API and MCP server in Rust; a public index at the API root6d ago

956

},

957

},

958

"schemas": {

959

"Error": {

960

"type": "object",

961

"required": ["error"],

962

"properties": {

963

"error": {

964

"type": "object",

965

"required": ["code", "message"],

966

"properties": {

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

967

"code": { "type": "string", "enum": codes },

API and MCP server in Rust; a public index at the API root6d ago

968

"message": { "type": "string" },

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step2d ago

969

"needed_scope": {

970

"type": "string",

971

"description": "On a 403 for an access token without the scope the call needs: that scope, such as `issues:write`.",

972

},

API and MCP server in Rust; a public index at the API root6d ago

973

},

974

},

975

},

976

},

977

},

978

},

979

})

980

}

981

982

#[cfg(test)]

983

mod tests {

984

use super::*;

985

986

#[test]

987

fn every_route_is_documented_once() {

988

let document = document();

989

let mut ids = Vec::new();

990

for (_, methods) in document["paths"].as_object().unwrap() {

991

for (_, operation) in methods.as_object().unwrap() {

992

ids.push(operation["operationId"].as_str().unwrap().to_owned());

993

}

994

}

995

for op in Op::ALL {

996

assert_eq!(

997

ids.iter().filter(|id| *id == op.name()).count(),

998

1,

999

"{}",

1000

op.name()

1001

);

1002

}

Webhooks: every event, to your own addresses, signed and retried5d ago

1003

let mut unique = ids.clone();

1004

unique.sort();

1005

unique.dedup();

1006

assert_eq!(unique.len(), ids.len(), "operation ids repeat");

API and MCP server in Rust; a public index at the API root6d ago

1007

}

1008

1009

#[test]

1010

fn path_and_query_inputs_are_not_repeated_in_the_body() {

1011

let document = document();

Agents as a team: lifecycle, merge queue, billing and a new shell5d ago

1012

let merge = &document["paths"]["/repos/{owner}/{name}/pulls/{number}/merge"]["post"];

API and MCP server in Rust; a public index at the API root6d ago

1013

let body = &merge["requestBody"]["content"]["application/json"]["schema"]["properties"];

1014

assert!(body.get("keep_issue_open").is_some());

1015

assert!(body.get("repo").is_none() && body.get("number").is_none());

Agents as a team: lifecycle, merge queue, billing and a new shell5d ago

1016

let list = &document["paths"]["/repos"]["get"];

API and MCP server in Rust; a public index at the API root6d ago

1017

assert_eq!(list["parameters"][0]["name"], "q");

1018

assert!(list.get("requestBody").is_none());

1019

}

1020

1021

#[test]

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

1022

fn every_operation_is_in_one_section() {

1023

for op in Op::ALL {

1024

let sections = SECTIONS

1025

.iter()

1026

.filter(|(_, _, ops)| ops.contains(&op))

1027

.count();

1028

assert_eq!(sections, 1, "{}", op.name());

1029

}

1030

}

1031

1032

#[test]

API and MCP server in Rust; a public index at the API root6d ago

1033

fn titles_read_as_sentences() {

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

1034

assert_eq!(title(Op::CreateIssue), "Create an issue");

API and MCP server in Rust; a public index at the API root6d ago

1035

assert_eq!(title(Op::Whoami), "Get the current user");

1036

}

Merge branch 'worktree-agent-ab2e39e11a6493412'3d ago

1037

1038

#[test]

1039

fn every_operation_has_an_example_response() {

1040

let examples = examples();

1041

assert!(!examples.is_empty(), "reference.json does not parse");

1042

let document = document();

1043

let mut known = Vec::new();

1044

for (path, methods) in document["paths"].as_object().unwrap() {

1045

for (method, operation) in methods.as_object().unwrap() {

1046

known.push(operation["operationId"].as_str().unwrap().to_owned());

1047

let example = &operation["responses"]["200"]["content"]["application/json"]["example"];

1048

assert!(!example.is_null(), "{method} {path} has no example response");

1049

}

1050

}

1051

for id in examples.keys() {

1052

assert!(known.contains(id), "reference.json names {id}, which is not an operation");

1053

}

1054

}

1055

1056

#[test]

1057

fn example_requests_send_only_what_the_body_takes() {

1058

let document = document();

1059

for (path, methods) in document["paths"].as_object().unwrap() {

1060

for (method, operation) in methods.as_object().unwrap() {

1061

let content = &operation["requestBody"]["content"]["application/json"];

1062

let Some(example) = content["example"].as_object() else { continue };

1063

let properties = &content["schema"]["properties"];

1064

for key in example.keys() {

1065

assert!(!properties[key].is_null(), "{method} {path}: {key} is not in the body");

1066

}

1067

}

1068

}

1069

}

1070

1071

/// The docs site's copy of the document. Run with `G1T_WRITE_OPENAPI=1`

1072

/// to rewrite it after changing an operation.

1073

#[test]

1074

fn the_docs_copy_is_current() {

1075

let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../docs/src/data/openapi.json");

1076

let current = serde_json::to_string_pretty(&document()).unwrap() + "\n";

1077

if std::env::var_os("G1T_WRITE_OPENAPI").is_some() {

1078

std::fs::write(path, &current).unwrap();

1079

return;

1080

}

1081

let copy = std::fs::read_to_string(path).unwrap_or_default().replace("\r\n", "\n");

1082

assert!(

1083

copy == current,

1084

"apps/docs/src/data/openapi.json is out of date: run G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi"

1085

);

1086

}

API reference: no example reads as a real secret3d ago

1087

Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API3d ago

1088

/// The reference shows responses as they are sent: `snake_case`.

1089

#[test]

1090

fn example_responses_are_snake_case() {

1091

let document = document();

1092

for (path, methods) in document["paths"].as_object().unwrap() {

1093

for (method, operation) in methods.as_object().unwrap() {

1094

let example = &operation["responses"]["200"]["content"]["application/json"]["example"];

1095

let leaked = g1t_kit::wire::camel_case_keys(example);

1096

assert!(leaked.is_empty(), "{method} {path} shows {leaked:?}");

1097

}

1098

}

1099

}

1100

API reference: no example reads as a real secret3d ago

1101

/// Examples never hold anything that reads as a real credential, which

1102

/// secret scanners rightly flag in a public repository: they end in `…`

1103

/// after the prefix, as `whsec_…` and `g1t_…` do.

1104

#[test]

1105

fn examples_hold_no_real_looking_secrets() {

Fast pages, required checks on the branch, self-hosted runners, honest incidents2d ago

1106

let prefixes = ["whsec_", "g1t_", "g1tr_", "g1trt_", "sk_live_", "sk_test_", "ghp_", "github_pat_", "xoxb-", "AKIA"];

API reference: no example reads as a real secret3d ago

1107

for (line, text) in REFERENCE.lines().enumerate() {

1108

for prefix in prefixes {

1109

let mut rest = text;

1110

while let Some(at) = rest.find(prefix) {

1111

let after = &rest[at + prefix.len()..];

1112

let run = after.chars().take_while(|c| c.is_ascii_alphanumeric()).count();

1113

assert!(

1114

run < 12,

1115

"reference.json line {}: `{prefix}` followed by {run} characters reads as a real secret; write `{prefix}…`",

1116

line + 1

1117

);

1118

rest = after;

1119

}

1120

}

1121

}

1122

}

API and MCP server in Rust; a public index at the API root6d ago

1123

}