API endpoint example v2026-04-17

This page is a fully-worked example of the api template — showing what REST reference pages look like with real :::endpoint directives. The content is fictional; the structure mirrors what an agency API reference would contain.

Endpoints on this page are for illustration only. For the real GitHub Branches API (the inspiration for this example), see the GitHub REST API docs.

Overview

All endpoints require a valid API token. For an overview of authentication and rate limits, see the installation guide. Requests are rate-limited to 5,000 calls per hour per token.

Endpoints

List branches

GET/repos/{owner}/{repo}/branches

Lists branches for the specified repository. Results are paginated — check the Link response header for next/prev URLs.

Path parameters

ownerstringRequired: The account that owns the repository.
repostringRequired: The name of the repository.

Query parameters

protectedboolean: When true, returns only protected branches.
per_pageinteger: Results per page (max 100).
Default: 30
pageinteger: Page number of the results to fetch.
Default: 1

Responses

Status code	Description
`200`	Returns an array of short branch objects.
`404`	Repository does not exist or the token lacks access.

Request example

curl -L \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/branches

await octokit.request('GET /repos/{owner}/{repo}/branches', {
  owner: 'OWNER',
  repo: 'REPO',
})

response = requests.get(
    f"https://api.github.com/repos/{owner}/{repo}/branches",
    headers={"Accept": "application/vnd.github+json"},
)

Response example

[
  {
    "name": "main",
    "commit": {
      "sha": "c5b97d5ae6c19dc5df71a34c7fbeeda2479ccbc",
      "url": "https://api.github.com/repos/OWNER/REPO/commits/c5b97d5ae6c19dc5df71a34c7fbeeda2479ccbc"
    },
    "protected": true
  },
  {
    "name": "develop",
    "commit": {
      "sha": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
      "url": "https://api.github.com/repos/OWNER/REPO/commits/a1b2c3d4e5f60718293a4b5c6d7e8f9012345678"
    },
    "protected": false
  }
]

Get a branch

GET/repos/{owner}/{repo}/branches/{branch}

Returns a single branch, including its latest commit and protection status. Pass the branch name without URL-encoding — the API normalizes slashes.

Path parameters

ownerstringRequired: The account that owns the repository.
repostringRequired: The name of the repository.
branchstringRequired: The name of the branch. Cannot contain wildcards.

Responses

Status code	Description
`200`	Returns the branch object.
`301`	The branch was renamed.
`404`	Branch or repository does not exist.

Request example

curl -L \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/branches/main

Response example

{
  "name": "main",
  "commit": {
    "sha": "c5b97d5ae6c19dc5df71a34c7fbeeda2479ccbc",
    "url": "https://api.github.com/repos/OWNER/REPO/commits/c5b97d5ae6c19dc5df71a34c7fbeeda2479ccbc"
  },
  "_links": {
    "self": "https://api.github.com/repos/OWNER/REPO/branches/main",
    "html": "https://github.com/OWNER/REPO/tree/main"
  },
  "protected": true,
  "protection": {
    "enabled": true,
    "required_status_checks": {
      "enforcement_level": "non_admins",
      "contexts": ["ci/build", "ci/test"]
    }
  }
}

Rename a branch

POST/repos/{owner}/{repo}/branches/{branch}/rename

Rename a branch and update any refs that point to it. Pull requests, webhooks, and other branch-aware features update automatically.

Path parameters

ownerstringRequired
repostringRequired
branchstringRequired: The current branch name.

Body parameters

new_namestringRequired: The desired new name for the branch.

Responses

Status code	Description
`201`	Returns the renamed branch object.
`403`	The token lacks write permission.
`422`	The new name is invalid or already exists.

Request example

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"new_name": "trunk"}' \
  https://api.github.com/repos/OWNER/REPO/branches/main/rename

Response example

{
  "name": "trunk",
  "commit": { "sha": "...", "url": "..." },
  "protected": true
}

Delete a branch

Deprecated

DELETE/repos/{owner}/{repo}/branches/{branch}

This endpoint is deprecated and will be removed in the next API version. Use the DELETE /repos/{owner}/{repo}/git/refs/heads/{branch} endpoint instead.

Path parameters

ownerstringRequired
repostringRequired
branchstringRequired: The name of the branch to delete.

Responses

Status code	Description
`204`	Branch deleted.
`403`	The branch is protected.
`404`	Branch does not exist.

What this page demonstrates

Four :::endpoint directives in a single page, each rendering its own two-column layout.
apiVersion frontmatter producing the version pill.
deprecated: true on the last endpoint rendering the Deprecated pill.
Parameter sections (pathParameters, queryParameters, bodyParameters) auto-rendering only when populated.
:::code-group nested inside the #request slot for multi-language code alternatives.
Plain fenced code blocks inside #response when a single example is enough.