API

Every endpoint except sign-in, invitation links, health checks and the webhook needs a signed-in session or an API token. Endpoints about an organization take its name in the x-kodmos-org header, and changes need the roles above. Answers are JSON.

On Team and Business, make a token under Settings → API tokens and send it as Authorization: Bearer kodmos_…. A token belongs to one organization, so it needs no x-kodmos-org header. You see it once, when it is made; Kodmos keeps only a fingerprint.

• Yours: acts as you, never above your role at the time of each request, and stops working if you lose access.
• The organization’s (owner only): acts as a bot named after it, like release-ci[bot], and keeps working when people leave.

Each token also has scopes, and every endpoint below needs one: Read for anything you can see, Answer to give branches, Plan for events and release trains, Deploy to deploy and run flows, and Edit flows. Deploy and Edit flows need a DevOps token. Your account, people, billing, Slack and tokens themselves only take a signed-in session.

Once a branch’s tests pass, CI can answer for its repository in the next open event that deploys it. It only needs the repository and the branch:

- name: Tell Kodmos the branch is ready
  if: success()
  run: |
    curl -fsS -X POST "$KODMOS_URL/api/answers" \
      -H "Authorization: Bearer $KODMOS_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"repo\": \"$GITHUB_REPOSITORY\", \"branch\": \"$GITHUB_REF_NAME\"}"
  env:
    KODMOS_URL: https://kodmos.example.com
    KODMOS_TOKEN: ${{ secrets.KODMOS_TOKEN }}

Send {"repo": …, "skip": true} to say the repository is not deploying this time, and eventId to answer for a particular event. If no open event deploys the repository, the answer is 404.