POST /api/repos/connect

Summary

Connects a GitHub repository to the platform, creates a doc site, and queues an initial full-scan job.

Intent

Allows a customer to link a GitHub repository so the platform can automatically extract, enrich, and publish API documentation from that repo’s source code.

Parameters

Name	Type	Required	Description
githubRepoId	string	Yes	The GitHub repository’s numeric or string ID.
githubRepoName	string	Yes	The full repository name in ‘owner/repo’ format (e.g. ‘acme/my-api’).
installationId	string	Yes	The GitHub App installation ID that grants access to the repository.
customerId	string	Yes	The platform customer ID to associate this repository with.
branch	string	No	The branch to track. Defaults to ‘main’ if not provided.

Request example

curl -X POST https://maps.google.com//api/repos/connect \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "githubRepoId": "123456789",
    "githubRepoName": "acme/my-api",
    "installationId": "987654321",
    "customerId": "cust_abc123",
    "branch": "main"
  }'

Response example

{
  "repoId": "a3f8c2e1d4b7e9f0c1a2",
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}

Error cases

• 400 — One or more of the required fields (githubRepoId, githubRepoName, installationId, customerId) is missing from the request body.
• 400 — githubRepoName is not in the required ‘owner/repo’ format (e.g. missing the slash, or either part is empty).

Gotchas

• githubRepoName must be exactly in ‘owner/repo’ format — a bare repo name or a URL will be rejected with a 400 error.
• The repoId returned is deterministically derived from a SHA-256 hash of installationId and githubRepoId, so connecting the same repo twice with the same installationId will produce the same repoId.
• If the branch field is omitted, the platform defaults to tracking ‘main’. Ensure your default branch matches or explicitly pass the correct branch name.
• A doc site and an initial full-scan job are created automatically on every successful connect call. Calling this endpoint multiple times for the same repo will create duplicate doc sites and jobs.
• If GitHub is unreachable when the endpoint is called, the queued job will use ‘HEAD’ as the commit SHA instead of the actual latest commit hash, which may affect incremental diff tracking.