Repositories

A repository is a private Git store owned by your user. There are no public repos in the product today.

Git objects live in S3 as layer tarballs. The default is Amendable platform storage. You do not pass a storage flag for that. Pro accounts can instead bring your own Amazon S3 bucket.

Name rules

• Recommended: ^[a-z0-9_-]+$
• Web UI: 1 to 32 characters, that same pattern
• API: 1 to 64 characters. The API currently accepts spaces and uppercase; the website form rejects them. Prefer the recommended pattern so clone URLs stay usable.
• Unique per user. POST returns 409 if the name is taken.

Create

curl

curl -sS -X POST https://api.amendable.io/v1/repositories \
  -H "Authorization: Bearer $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-repo","description":"scratch space"}'

amendable-cli

amendable repo create my-repo --description "scratch space"

Python

# pip install httpx
import os
import httpx

httpx.post(
    "https://api.amendable.io/v1/repositories",
    headers={"Authorization": f"Bearer {os.environ['AMENDABLE_TOKEN']}"},
    json={"name": "my-repo"},
).raise_for_status()

Needs grant API_REPOS_WRITE or ALL.

Response (201):

{
  "username": "demo",
  "name": "my-repo",
  "active": true,
  "description": "scratch space",
  "storage_source": "platform"
}

storage_source says which S3 bucket holds this repo’s Git layer objects:

Value	Where objects live
platform	Amendable’s S3. The default if you have no BYO bucket.
default	Your account default BYO bucket.
repo	The specific BYO bucket you passed at create.

You cannot move a repo to a different bucket later.

Optional: your S3 bucket

Skip this unless you already set up bring-your-own S3. That is a Pro Amazon S3 bucket Amendable writes layers/*.tar.gz into, using OIDC.

After Verify succeeds (status is ACTIVE), copy the bucket UUID from Settings → Bring-your-own storage or GET /v1/storage-buckets (needs API_STORAGE). Pass that id when you create the repo.

curl

curl -sS -X POST https://api.amendable.io/v1/repositories \
  -H "Authorization: Bearer $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-repo","storage_bucket_id":"11111111-1111-1111-1111-111111111111"}'

amendable-cli

amendable repo create my-repo --storage-bucket-id 11111111-1111-1111-1111-111111111111

Python

# pip install httpx
import os
import httpx

httpx.post(
    "https://api.amendable.io/v1/repositories",
    headers={"Authorization": f"Bearer {os.environ['AMENDABLE_TOKEN']}"},
    json={
        "name": "my-repo",
        "storage_bucket_id": "11111111-1111-1111-1111-111111111111",
    },
).raise_for_status()

Omit the id to use the account default BYO bucket, or platform storage if you have no default. The bucket must be ACTIVE and owned by you. Binding cannot change later.

Note

The web create form can seed a README so the browse UI is not empty. The API creates an empty Git repository. Push at least one commit before the tree view has files.

List and get

amendable repo list --json
amendable repo get my-repo --json

curl -sS https://api.amendable.io/v1/repositories \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

curl -sS https://api.amendable.io/v1/repos/$AMENDABLE_USERNAME/my-repo \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

List and get need API_REPOS_READ. API_REPOS_WRITE includes read, and so does ALL. They only return repositories the token’s scope can see.

Clone URL and browse URL

git clone https://amendable.io/r/<username>/<repo>.git
https://amendable.io/r/<username>/<repo>
https://amendable.io/r/<username>/<repo>/commits/<branch>
https://amendable.io/r/<username>/<repo>/blob/<branch>/<path>
https://amendable.io/r/<username>/<repo>/raw/<branch>/<path>

amendable repo url my-repo prints the clone URL.

To list the tree or download a file over the REST API without cloning, see Fetch files. That needs API_COMMITS_READ. The browse /blob/ and /raw/ URLs above are the account owner’s website session.

Delete

amendable repo delete my-repo --yes

curl -sS -X DELETE \
  https://api.amendable.io/v1/repos/$AMENDABLE_USERNAME/my-repo \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

204 on success. 404 if the name is wrong or the token cannot see it. Needs API_REPOS_WRITE or ALL.

Layer objects are removed later from platform or BYO storage. Deleting a repo does not delete a BYO bucket. The bucket cannot be deleted while any repo still depends on it.

Quotas that block create

Limit	Free default	Error
Active repositories	5	422 active quota exceeded
Total repositories (including inactive)	25	422 total quota exceeded

Paid plans raise both. See Usage and quotas.