# Create managed repositories from an agent

Base URL: https://stargit.com

Machine-readable API description: https://stargit.com/static/docs/hosting-openapi.json

Sign in at /hosting/new, select the hosting destination, and create an access token with **Allow agents to create repositories** checked. Enable **Allow push as well as clone** only if the agent should also push code. Tokens expire after 90 days and can be revoked. Each token belongs to one hosting destination and acts as its owning account. Existing Git tokens do not automatically gain creation permission.

Supply the token through your secret manager as `STARGIT_TOKEN`. Never put it in a repository, prompt, clone URL, or log. The commands below require curl and jq.

## 1. Discover the destination

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

The response contains `owner.name`, `owner.address`, and `providers` with `id`, `hostname`, `available`, and `message`. Use the returned provider ID; do not guess it. The owner address is automatic and must not be supplied on creation.

## 2. Create a repository

Set `PROVIDER_ID` to the discovered ID. Choose a request ID once for this logical operation and retain it across retries. It is not a credential.

```sh
export REQUEST_ID="my-agent-task-2026-001"
jq -n --argjson provider "$PROVIDER_ID" '{
  provider_id: $provider,
  name: "my-project",
  description: "What this project does",
  visibility: "private",
  default_branch: "main",
  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
```

`name` and `provider_id` are required. Names use lowercase letters, numbers, underscores and hyphens, start with a letter or number, and have at most 80 characters. `description` is optional (up to 1000 characters). Defaults: private visibility, main branch, README enabled. Set `readme: false` for an empty repository when pushing an existing project.

A new request returns HTTP 202 with `uuid`, `state`, `status_url`, `retry_after_seconds`, `namespace`, and `name`. Clone URLs are null until ready. Repeating the same request ID and identical JSON returns the same repository (HTTP 200). Reusing that ID with different settings returns HTTP 409.

## 3. Poll until ready

```sh
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 an overall timeout in your agent. States: `provisioning`, `ready`, `error`. Only clone or push when `state` is `ready`. Read `https_url`, `clone_url` (SSH), `review_url`, and `overview_url` from the response. HTTPS uses the token as the Git password through your credential helper; SSH uses an independently registered SSH key.

If state is `error`, inspect the `error` message. To retry provisioning the same repository:

```sh
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $STARGIT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"retry"}' \
  "https://stargit.com/api/hosting/repositories/$REPOSITORY_UUID"
```

## Agent handling

- 400: correct the request; do not blindly retry.
- 401: missing, expired, or revoked authentication.
- 403: missing creation permission or wrong destination.
- 404: repository unavailable to this account.
- 409: conflict, repository limit, or destination unavailable; inspect `error`.
- Network failure: retry creation with the **same request ID and JSON**, never a new ID.

Private is the default. Tokens cannot create for another account, manage tokens/SSH keys, or bypass the existing human PR review process. This API creates managed repositories; it does not start agents, provision compute, or grant automatic merge approval. Current account limit: 20 managed repositories.