KIP Interfaces — Read-only AI API Reference v0.1.45

Start here: first successful request

The implemented API provides read-only GitHub access for authorized clients. There are no write or commit endpoints. The GET-only operations were checked against ai-api.php in the v0.1.45 development source. Production execution and authorization have not been independently tested.

Base URL: https://www.tiltedlogic.org/KIP-Interfaces/ai-api.php (HTTPS). Method: GET for every operation. Authentication: Authorization: Bearer ciai_ followed by 64 lowercase hexadecimal characters. The token is a separate client credential, not a GitHub personal access token.

One-time administrator prerequisites

Register the intended client in Administration → Clients.
Configure a GitHub development credential under GitHub Operations → Named Credentials.
Enroll the intended owner/repository under GitHub Operations → Repositories using that credential.
Under GitHub Operations → Client Assignments, assign that credential to the registered client and grant Read.
Open AI API Tokens, select the client and issue a labeled API token. Copy it securely when issued. Token creation requires an existing Read assignment.

See Administrator Guide for what each object means and maintenance instructions.

First request (copy and adapt)

# Replace with a newly issued client API token; never commit this file or variable.
export CI_API_TOKEN='ciai_REPLACE_WITH_YOUR_64_HEX_CHARACTERS'
BASE='https://www.tiltedlogic.org/KIP-Interfaces/ai-api.php'
curl --fail-with-body --show-error \
  -H "Authorization: Bearer $CI_API_TOKEN" \
  "$BASE?op=repositories"

Expected JSON shape (illustrative values, not a live response):

{"client":"example-client","repositories":[{"name":"owner/repository","capabilities":["read","head","compare"]}]}

An empty repositories array means no accessible repository was returned; verify the assignment and enrollment. Do not treat HTTP 200 alone as proof that a specific repository is authorized.

Endpoint reference

Operation	Query parameters	Response fields
`repositories`	`op=repositories`	`client`, `repositories[]` with `name`, `capabilities[]`
`branches`	`op=branches&repo=owner/repository`	`repo`, `branches[]` (`name`, `sha`, `protected`), `truncated`
`head`	`op=head&repo=owner/repository&branch=main`	`repo`, `branch`, `head_sha`
`file`	`op=file&repo=owner/repository&ref=main&path=README.md`	`repo`, `path`, `ref`, `commit_sha`, `blob_sha`, `size`, `encoding`, `content`
`compare`	`op=compare&repo=owner/repository&from=main&to=feature`	`repo`, `base_sha`, `head_sha`, `merge_base_sha`, `ahead_by`, `behind_by`, `status`, `files[]`, `truncated`

repo is owner/repository. branch defaults to main for head. For file, ref and path are required; the file path is relative to the repository root. For compare, both from and to are required. Use URL encoding for all values. file content is base64 and limited to 1 MiB. Branch results request at most 100 entries and set truncated when the count equals 100. Comparison results indicate truncation at 300 files.

Follow-on requests

REPO='owner/repository'
curl --fail-with-body -G -H "Authorization: Bearer $CI_API_TOKEN" \
  --data-urlencode 'op=branches' --data-urlencode "repo=$REPO" "$BASE"
curl --fail-with-body -G -H "Authorization: Bearer $CI_API_TOKEN" \
  --data-urlencode 'op=head' --data-urlencode "repo=$REPO" \
  --data-urlencode 'branch=main' "$BASE"
curl --fail-with-body -G -H "Authorization: Bearer $CI_API_TOKEN" \
  --data-urlencode 'op=file' --data-urlencode "repo=$REPO" \
  --data-urlencode 'ref=main' --data-urlencode 'path=README.md' "$BASE"
curl --fail-with-body -G -H "Authorization: Bearer $CI_API_TOKEN" \
  --data-urlencode 'op=compare' --data-urlencode "repo=$REPO" \
  --data-urlencode 'from=main' --data-urlencode 'to=feature' "$BASE"

To read a reproducible file version, first request head, capture head_sha, then use that SHA as the ref for file. The file response also returns its resolved commit_sha. Decode content only after checking encoding and size.

Error contract

Every error response has an error object with code and message.

HTTP status	Code	Meaning / action
400	`invalid_request` or `unknown_operation`	Fix query syntax, missing parameters or operation
401	`unauthorized`	Missing, malformed, unknown or revoked bearer token
403	`unauthorized`	Client lacks Read assignment, development credential or repository enrollment
405	`method_not_allowed`	Use GET rather than POST/PUT/DELETE
502	`upstream_error`	GitHub or server operation failed; inspect server logs and retry after diagnosis

Example error: {"error":{"code":"unauthorized","message":"Bearer API token required."}}.

Credential rotation and security

Only administrators issue or revoke API tokens. A token represents a registered client and its existing assignment; changing the token does not enroll a repository. Revoke retired/compromised tokens, issue replacements and update clients' secret storage. Never put bearer tokens in URLs, source control, screenshots or application logs.

Implementation boundary and verification

This reference is derived from ai-api.php and lib/ai-api.php in the supplied package. It is not a live endpoint test. There is no confirmed OpenAPI schema or automated documentation-driven integration test in the baseline. Those are Phase 4 documentation and testing work items, not claims of completed functionality.

Historical release notes and development appendices

Earlier checkpoint descriptions are retained in the versioned Release-Notes-v0.1.41.md through Release-Notes-v0.1.44.md and historical continuity records. They do not describe current v0.1.45 behavior.