---
title: "Agents and the commit API"
description: "Read files and write a commit in one API call, with expectedHeadSha so a branch that moved isn't overwritten."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents and the commit API

An agent can work with real `git` (clone, commit, push with a bot's key, as in the
[Quickstart](/git/quickstart)) or through the API without a checkout. The examples use an
[API key](/iam/api-keys) or a bot's key in `$EZGH_API_KEY`, and `$ORG_ID`, `$PROJECT_ID` and
`$REPO` (`gtr_…`).

## Read

[GetContents](/git-api/GetContents/) returns a file at a branch, tag or commit (`ref`, the
default branch when absent), or a folder's entries. The path is one segment, with `/` encoded:

```sh
curl -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://git-api.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/repositories/$REPO/contents/src%2Fheader.tsx?ref=main"
```

A file's `content` is base64, and `null` past 1 MiB: read those bytes from
[GetBlob](/git-api/GetBlob/) with the file's `sha`. [GetTree](/git-api/GetTree/) with
`recursive=true` lists every file. [GetBranch](/git-api/GetBranch/) gives the branch's
head commit.

## Write a commit

[CreateCommit](/git-api/CreateCommit/) makes one commit on a branch from a list of
`write`, `delete` and `move` changes. `expectedHeadSha` is the branch's head you read; the commit is
refused if the branch moved since:

```sh
curl -X POST -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "branch": "agent/fix-header",
    "startFrom": "main",
    "expectedHeadSha": null,
    "message": "Fix the header on small screens",
    "changes": [
      {"op": "write", "path": "src/header.tsx", "content": "export function Header() {\n  return <header className=\"truncate\">Storefront</header>\n}\n"},
      {"op": "delete", "path": "src/old-header.css"}
    ]
  }' \
  "https://git-api.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/repositories/$REPO/commits"
```

- A new branch starts from `startFrom` (a branch, tag or commit; the default branch when absent), and
  `expectedHeadSha` is `null`. An existing branch needs `expectedHeadSha`.
- `content` is text; binary files go as `contentBase64`. `mode` `100755` makes a file executable.
- The answer is `201` with the new commit's `sha`. The committer is always you; `author` sets the
  author's name and email.
- A change set that changes nothing is `400 empty_commit`. Branch rules apply as for a push: a
  protected branch is `409 blocked_by_rule`, with the rule's reason.

## When the branch moved

`409 conflict` means the branch's head isn't `expectedHeadSha` any more: someone else pushed or
committed. Read the branch and the files you change again, redo the change on the new head, and send
it with the new `expectedHeadSha`. Use a new `Idempotency-Key` for the new attempt; repeating the
same key replays the first answer.

## Then open a pull request

```sh
ezgh git prs create site --head agent/fix-header --title "Fix the header on small screens"
```

See [Pull requests](/git/pull-requests). A CI bot or the agent itself reports results on the head
commit with [`ezgh git checks report`](/cli/reference/git-checks-report).

Source: https://docs.ezghcloud.com/git/agents/index.mdx
