For agents

This page is for an autonomous agent (or a human following a script). It assumes you have not used Amendable before. Follow the steps in order. Do not invent hosts, header names, or IAM policy shapes.

Caution

Do not print access tokens, webhook secrets, or AWS secret keys in logs. Mask them.

What Amendable is

Amendable is hosted Git storage with an HTTP API.

• Site and Git HTTPS: https://amendable.io
• API: https://api.amendable.io
• Docs: https://docs.amendable.io/
• OpenAPI UI: https://api.amendable.io/docs
• Clone URL pattern: https://amendable.io/r/{username}/{repo}.git
• API auth: Authorization: Bearer (examples: Authentication)
• Git auth: HTTPS Basic. Username = Amendable username. Password = access token. See Git over HTTPS.

You do not need AWS for clone and push. You need AWS only for bring-your-own S3.

Goal for a basic test

1. Create an account (or use credentials you were given).
2. Create an access token.
3. Create a repository.
4. git clone, commit, git push.
5. Open the browse URL and confirm the file is there.
6. Delete the repository if it was a scratch repo.

If this environment cannot run git comfortably (missing git, broken HTTPS, no disk), use any machine that can run git and HTTPS, then continue from step 4.

Step A. Account

If you already have AMENDABLE_TOKEN, skip steps A and B and go to step C. You do not need AMENDABLE_USERNAME yet; create returns it.

Otherwise:

1. Open https://amendable.io/sign-up.
2. Register with a real email you control, or credentials provided in the task.
3. Sign in at https://amendable.io/sign-in. If the account has MFA enrolled, the site asks for TOTP or FIDO2 after the password. Git and the API still use the access token only. See Authentication.

If sign-up is blocked (captcha, email confirm) and you were not given a token, stop and report the blocker. Do not guess a token.

Step B. Access token

In the signed-in UI, open https://amendable.io/access-tokens/ (or Settings → Access tokens).

Create a token:

• Name: agent
• Scope: All repositories
• Grant All Permissions: on

Copy the secret. Export it:

export AMENDABLE_TOKEN='the-secret'

Check it:

curl -sS -o /tmp/amendable-usage.json -w "%{http_code}\n" \
  "https://api.amendable.io/v1/account/usage" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"
cat /tmp/amendable-usage.json

Expect HTTP 200 and JSON with repos, storage_bytes, transfer_bytes. HTTP 401 means Authorization: Bearer is missing or the token is wrong.

Step C. Create a repository

Pick a unique name matching ^[a-z0-9_-]+$. Example: agent-try-1. See Repositories.

export AMENDABLE_REPO=agent-try-1

curl -sS -X POST "https://api.amendable.io/v1/repositories" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$AMENDABLE_REPO\"}" | tee /tmp/amendable-repo.json

Expect HTTP 201. Read username from the JSON. That is AMENDABLE_USERNAME.

export AMENDABLE_USERNAME="$(python3 -c 'import json; print(json.load(open("/tmp/amendable-repo.json"))["username"])')"
echo "$AMENDABLE_USERNAME/$AMENDABLE_REPO"

HTTP 409: the name is taken. Change AMENDABLE_REPO and retry. HTTP 422: you hit the free quota (5 active repos). Delete an unused repo or use a different account.

The web UI also creates repos. Either path is fine. The API is easier to automate.

Step D. Git clone and push

WORKDIR=$(mktemp -d)
cd "$WORKDIR"
git clone "https://${AMENDABLE_USERNAME}:${AMENDABLE_TOKEN}@amendable.io/r/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}.git"
cd "$AMENDABLE_REPO"
git config user.email "agent@example.com"
git config user.name "Amendable agent"
echo "hello from $(date -u +%FT%TZ)" > hello.txt
git add hello.txt
git commit -m "Add hello.txt"
git push -u origin HEAD:main
git remote set-url origin "https://amendable.io/r/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}.git"

If main is rejected, push HEAD:master or check refs:

git ls-remote "https://${AMENDABLE_USERNAME}:${AMENDABLE_TOKEN}@amendable.io/r/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}.git"

Empty repos accept whatever branch you push first. The first commit may have an empty tree (no files); git commit --allow-empty is fine. After the first push, the default branch is that branch.

Auth failures (fatal: Authentication failed):

• Token missing GIT_HTTP_WRITE (and GIT_HTTP_READ). Recreate with Grant All, or grants GIT_HTTP_READ,GIT_HTTP_WRITE.
• Token expired.
• You used the account password instead of the token.

Step E. Confirm in the API and the UI

curl -sS "https://api.amendable.io/v1/repos/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}/branches" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

You need API_COMMITS_READ or ALL for that endpoint. Grant All includes it. Before the first push, that call is 200 with {"branches":[],"default_branch":"master"}, not 404. GET .../commits and GET .../contents on an empty repo are 404 No commit found in the repository.

To read hello.txt without cloning:

curl -sS "https://api.amendable.io/v1/repos/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}/contents" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

curl -sS "https://api.amendable.io/v1/repos/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}/contents/hello.txt" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

Directories return JSON. Files return raw bytes. See Fetch files.

Browse (signed in as the account owner):

https://amendable.io/r/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}
https://amendable.io/r/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}/blob/main/hello.txt

Step F. Optional webhook ping

Only if you have a public HTTPS URL that returns 2xx. example.com returns 405. Use a receiver you control, or httpbin for a ping:

curl -sS -X POST "https://api.amendable.io/v1/webhooks" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://httpbin.org/post","events":["push","ping"]}'

Save secret from the create response. Send a ping, then verify HMAC-SHA256 hex of the raw body against header X-Amendable-Signature. See Webhooks.

Do not point webhooks at localhost or RFC 1918 addresses. Production rejects those.

Step G. Clean up

curl -sS -o /dev/null -w "%{http_code}\n" \
  -X DELETE "https://api.amendable.io/v1/repos/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

Expect 204.

Using amendable-cli instead of curl

The CLI is optional. The curl steps above are enough. To use it, install amendable (Install the CLI), then:

amendable login
amendable repo create agent-try-1
amendable repo clone agent-try-1

Login opens a grant URL. If you cannot drive a browser, skip login and set:

export AMENDABLE_TOKEN='...'
amendable repo create agent-try-1

If you are setting up BYO S3

Stop. Read Bring your own S3 first.

Hard rules:

• Amazon S3 must use OIDC. Static AWS access keys are rejected for provider S3.
• The bucket can be in any AWS region. Pass that region when you register the bucket.
• Copy issuer, audience, and subject from GET /v1/storage-buckets/oidc-setup. Do not invent sub.
• Subject is account:{user-uuid}, not account:{username}.
• After IAM is in place, POST /v1/storage-buckets/{id}/verify. Status must become ACTIVE before you bind a repo.
• Do not delete objects under {prefix}layers/. That is data loss. Verify does not check that those objects still exist.

Bring your own S3 leads with the AWS console (no extra tools), then an AWS CLI script, then Terraform if you already manage AWS as code. Fill account id, bucket name, region, and user UUID. Issuer, audience, and subject come from the oidc-setup payload.

Failure table

Symptom	Likely cause
API 401	Missing Authorization: Bearer header, or token typo
API 403 on storage	BYO requires Pro, or the token lacks API_STORAGE
API 409 on create repo	Name already used
API 422 on create repo	Active or total repo quota
Empty-repo GET branches is 200	Expected. branches is []. 404 No commit found is GET commits or contents
API 403 on contents	Transfer quota, or the file is larger than 64 MiB. Clone over Git for bigger files.
Git auth failed	Token is not the HTTPS password, or missing GIT_HTTP_* grants
Git 500 after BYO	Layer object missing or IAM cannot GetObject on layers/. Click Verify for IAM only.
Webhook never arrives	URL not HTTPS, private IP, or events list does not include push

Do not

• Do not call https://git.amendable.io. Git is on https://amendable.io.
• Do not use platform bucket names (amendable-repos-*, amendable-download-*) as BYO buckets.
• Do not put long-lived AWS keys on Amazon S3 BYO. Use the IAM role + OIDC path.