StarGit API

One connection. Clear permissions.

Create a private connection prompt, paste it into your agent, and work with your repositories, PRs, handovers and agent evidence. Start with read access; add scoped changes when you need them.

The download includes a Python command client and optional local MCP server. Every write uses a recorded user request, current playbook revision and stable retry key. Human PR approval and merge remain in the web review workflow.

Account connections, Git clone credentials and legacy StarBridge API keys have separate purposes. Browser-only ChatGPT requires an execution environment or a hosted connector; this release provides local stdio MCP.

StarGit account API keys

Sign in to create and manage your API keys.

Create a repository from your agent or terminal

Use the managed repository API to discover a destination, create a repository, and retrieve its HTTPS and SSH clone URLs. No browser session is required for these calls.

Choose the right credential

Hosting tokens expire after 90 days and are limited to one destination. Existing Git tokens need explicit creation permission. Set STARGIT_TOKEN through your secret manager; never commit it or include it in a clone URL.

1. Discover your destination

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $STARGIT_TOKEN" \
  https://stargit.com/api/hosting/setup

Use the returned providers[].id as PROVIDER_ID when available is true. Your account owns the repository automatically.

2. Create once, retry safely

export REQUEST_ID="my-agent-task-001"
jq -n --argjson provider "$PROVIDER_ID" '{
  provider_id: $provider,
  name: "my-project",
  description: "What this project does",
  visibility: "private",
  readme: true
}' > repository-request.json

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $STARGIT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  --data-binary @repository-request.json \
  https://stargit.com/api/hosting/repositories > repository-result.json

HTTP 202 means provisioning has started. Set readme: false for an empty repository. Repeat the same request ID and JSON after a network failure; the API returns the same repository. Changing the settings under that ID returns 409.

3. Wait for ready, then clone

REPOSITORY_UUID=$(jq -r .uuid repository-result.json)
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $STARGIT_TOKEN" \
  "https://stargit.com/api/hosting/repositories/$REPOSITORY_UUID"

Poll every three seconds with a bounded timeout. States are provisioning, ready, and error. When ready, use https_url or clone_url. For a failed setup, POST {"action":"retry"} to the same status URL.

Creation does not launch an agent or authorize a merge. Use branches and pull requests for human review. The hosting token does not authenticate browser-only PR or queue endpoints.

400: invalid input · 401: invalid/expired token · 403: permission or destination mismatch · 404: repository unavailable to this account · 409: conflict, limit, or destination not ready. Read the JSON error before retrying.

Publish project context. Continue on another computer.

Attach versioned handovers and Markdown documents to a repository, inspect them in StarGit, then restore their original project paths. Source code stays in Git.

Use an active StarGit account API key as Authorization: Bearer. Create an account API key, then run python3 stargit_handover.py auth on the new computer. The command also accepts STARGIT_API_KEY or an owner-only credentials file. Each teammate uses their own account. Git hosting tokens and SSH keys do not authenticate these endpoints.

python3 stargit_handover.py --credentials-file /private/credentials.env publish \
  --repo REPOSITORY_UUID --root . --name continuation --title "Project continuation" \
  --file docs/handoffs/continuation.md --follow-links --dry-run

python3 stargit_handover.py --credentials-file /private/credentials.env pull \
  --repo REPOSITORY_UUID --revision PUBLICATION_UUID --root . --dry-run

Inspect the selection, then repeat without --dry-run. Pull checks the source commit, hashes and local conflicts before writing. Existing differing files are preserved. Agent instruction files require an explicit --include-instructions after review.

Handovers remain private even when the source repository is public. Owners and repository contributors can publish; members with read access can inspect and pull. Every update names its parent revision, so parallel agents cannot silently replace each other's publications.

Connect your own server with StarBridge

The core connection endpoints below are implemented in StarGit. Authentication differs between the StarBridge API and signed-in workspace actions.

StarBridge authentication

For a self-hosted StarBridge connection, generate an API key in your account, then use it to request tokens. Replace the example values with your own key and server identifier.

curl --request POST https://stargit.com/api/auth/token \
  --header "Authorization: Bearer $STARGIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"server_uuid":"YOUR_SERVER_UUID","scopes":"servers:register servers:heartbeat servers:poll servers:live-update"}'

The response contains access_token, refresh_token, api_key_uuid, and server_uuid. Refresh with POST /api/auth/refresh and JSON {"refresh_token":"…"}. Save the returned access token; it replaces the previous one. Use the access token as Authorization: Bearer … for the server endpoints.

Refresh an expired access token

jq -n --arg token "$STARGIT_REFRESH_TOKEN" '{refresh_token: $token}' | \
  curl --fail-with-body --silent --show-error \
  -H "Content-Type: application/json" --data-binary @- \
  https://stargit.com/api/auth/refresh

The refresh token has its own expiry. A revoked token or disabled/expired API key cannot refresh. Save the returned access token before your next StarBridge request.

Store credentials outside source control. StarBridge handles the connection lifecycle; follow its setup guide for the full server payloads.

Workspace operations use your session.