16 — Working with the API

Almost anything you can do in the interface can be done over HTTP too: backups, reporting, your own tools.

Authentication

Create an access token (chapter 10) and send it as a header on every request:

TOKEN=your-token
curl -H "Authorization: token $TOKEN" \
  https://forge.kabaforce.com/api/v1/user

A token is limited to the permissions you picked when creating it: do not grant write access for a read-only job.

Endpoints you will use most

Base address: https://forge.kabaforce.com/api/v1

Lists are paginated: ?page=2&limit=50.

Reading a file

curl -H "Authorization: token $TOKEN" \
  "https://forge.kabaforce.com/api/v1/repos/owner/project/contents/docs"

The content field comes back base64-encoded; asking for the raw file is usually simpler:

curl -H "Authorization: token $TOKEN" \
  https://forge.kabaforce.com/owner/project/raw/branch/main/readme.md

Creating and updating files

curl -X POST -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"aGVsbG8=","message":"add note","branch":"main"}' \
  https://forge.kabaforce.com/api/v1/repos/owner/project/contents/notes.md

content is base64. To update an existing file use PUT and send the file's current sha — that is what stops you from silently overwriting someone else's change.

Opening an issue

curl -X POST -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"login page shifts on mobile","body":"Steps: ..."}' \
  https://forge.kabaforce.com/api/v1/repos/owner/project/issues

Error codes

Rules

• Do not hard-code the token in a script; read it from an environment variable.
• For automation, create a separate narrow-scoped token instead of using your own broad one.
• If the job only reads, consider a deploy key instead (chapter 13).