Documentation · API reference

The konnos REST API

Plain HTTPS, JSON in and out. Mint an access token, then create and manage repositories and issues from your scripts, CI, and tools. Every call is scoped to exactly what your token allows.

Authentication

Mint a token first

There is exactly one endpoint that accepts your password: the one that creates a token. You authenticate it with HTTP Basic (your username and password), and it hands back a token you use for everything else.

# the ONLY endpoint that takes your password (HTTP Basic)
curl -X POST https://code.konnos.org/api/v1/users/<you>/tokens \
  -u "<you>:<password>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-token" }'

# -> { "name": "ci-token", "sha1": "9b2c...e1", "scopes": ["repo"] }

After that, send the token on every request with the Authorization header — never your password again:

Authorization: token <TOKEN>

Git over HTTPS uses the same token: when git push asks for a password, paste the token instead. Store it like a secret, rotate it freely, and revoke it in one click.

Base URLhttps://code.konnos.org

Endpoints

The core of the API

A handful of endpoints cover the everyday loop — make a repo, find your repos, read one, and track work with issues.

POST/api/v1/user/repos

Create a repository (private by default).

curl -X POST https://code.konnos.org/api/v1/user/repos \
  -H "Authorization: token <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "invoice-parser", "private": true }'

Response

{
  "id": 42,
  "name": "invoice-parser",
  "full_name": "you/invoice-parser",
  "private": true,
  "default_branch": "main",
  "clone_url": "https://code.konnos.org/you/invoice-parser.git",
  "html_url": "https://code.konnos.org/you/invoice-parser"
}
GET/api/v1/user/repos

List the repositories you can access.

curl https://code.konnos.org/api/v1/user/repos \
  -H "Authorization: token <TOKEN>"

Response

[
  {
    "name": "invoice-parser",
    "full_name": "you/invoice-parser",
    "private": true,
    "updated_at": "2026-06-27T14:09:00Z"
  }
]
GET/api/v1/repos/{owner}/{repo}

Get a single repository.

curl https://code.konnos.org/api/v1/repos/you/invoice-parser \
  -H "Authorization: token <TOKEN>"

Response

{
  "name": "invoice-parser",
  "full_name": "you/invoice-parser",
  "private": true,
  "default_branch": "main",
  "open_issues_count": 1
}
POST/api/v1/repos/{owner}/{repo}/issues

Open an issue on a repository.

curl -X POST https://code.konnos.org/api/v1/repos/you/invoice-parser/issues \
  -H "Authorization: token <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Handle multi-page PDFs", "body": "Parser stops after page 1." }'

Response

{
  "number": 1,
  "title": "Handle multi-page PDFs",
  "state": "open",
  "html_url": "https://code.konnos.org/you/invoice-parser/issues/1"
}
GET/api/v1/repos/{owner}/{repo}/issues

List issues on a repository.

curl "https://code.konnos.org/api/v1/repos/you/invoice-parser/issues?state=open" \
  -H "Authorization: token <TOKEN>"

Response

[
  {
    "number": 1,
    "title": "Handle multi-page PDFs",
    "state": "open"
  }
]

The API is growing — these are the stable basics today. Need something that isn't here yet? Tell us through the contact form.

Build on your own Git platform

Get an account, mint a token, and start automating against konnos in minutes.

Start freeMCP server