Overview
Afunana exposes an authenticated REST API. The web client, the VS Code extension, and any integration you build all use it. This page describes, at a logical level, the categories of information and operations the API provides. It does not list endpoints, methods, or request shapes — it is a map of what is available, not a call reference.
The API is served by the Afunana backend behind the same reverse proxy that fronts the web app. Requests are authenticated with a bearer token, and most data operations run in the context of a single collection resolved from the request (or the user's default collection). Access is further constrained by the caller's role and by per-collection permissions.
The following sections group the API by capability area.
Authentication & sessions
Callers obtain a token by signing in with a username and password. Once issued, a token identifies the user on subsequent requests, can be refreshed as it nears expiry, and can be revoked on sign-out. Additional operations cover retrieving the current user's profile, changing a password, self-service registration where enabled, and password-reset by email. Sign-in is rate-limited and locks an account after repeated failures. Only sign-in and the health check are reachable without a token; everything else requires one.
Programs
For a single program, the API returns its generated documentation together with its metadata — summary, business purpose, and structure. It also returns the program's relationships: the programs it calls, the programs that call it, the files it uses, and the copybooks it includes. Programs can be listed and searched across a collection. Where source is available, a program's source and a structured view of its control and data flow can be retrieved (see Source, below).
Files & SQL members
For a single file or table, the API returns its documentation and metadata, and it can preview a file's record layout and sample data. Files can be listed and searched. SQL members (for platforms that have them) can likewise be listed, and a single member returns a structured document: its type and summary, the operations it performs with citations back to the member's own source lines, the files and libraries it touches, related programs, and any risk or migration notes.
Data dictionary, cross-reference & field lineage
The API exposes the analyzed data dictionary — the fields discovered across the estate with their definitions and characteristics. For any field it can report which files contain it, where programs define it, and its lineage: how a field flows across program boundaries, classifying each reference by how the field is used and distinguishing source files from target files by I/O direction. At the program level, the same area provides the impact map — calls, callers, files used, and copybooks — plus collection-wide quality findings and cross-program parameter/interface mismatch reports from the most recent build.
A separate, user-curated data dictionary is also available: design-time fields, tables, logical-file and key layouts, reference tables, and grouped "apps." These are editable definitions that a team maintains by hand, and generated DDS/DDL can be produced from them.
Chat
The API lets a caller ask a natural-language question about a collection and receive a grounded answer. The answer can be returned in one response, or streamed incrementally so a UI can show progress as the assistant works. Chat sessions are scoped per user and per collection: they can be created, listed, read with their full message history, renamed, and deleted, and individual messages can be appended or removed. A question can carry an uploaded attachment (text or image), which is read into the conversation.
See Chat & RAG System.
Change plans
When a conversation produces a proposed change, it can be saved as a change plan — a titled, summarized set of steps. Saved plans can be listed and reviewed, approved or rejected or edited, and — where enabled for the deployment — executed against the live source system, with step-by-step progress reported as it runs. Execution is gated by configuration and by approval; nothing runs unattended.
Source read & approval-gated write-back
For a program that has source on the connected system, the API can fetch the member's source and, subject to authority, write source back to it. Source operations can be attributed to an individual developer's own sign-on so the action is authorized and logged under the real person rather than a shared service account; if no per-developer credentials are supplied, a service account is used. A failed sign-on or insufficient authority is reported back so the caller can correct credentials. Raw source is available only through the REST API — it is never exposed over MCP. Related operations list and fetch copybooks and run a syntax check on submitted code.
Bring Your Own Documents
Supporting documents (such as specifications or standards, in common document formats) can be uploaded into a collection's knowledge base, where they are indexed alongside the analyzed source so they are retrieved in chat like any other knowledge. Uploaded documents can be listed, their content retrieved, and removed again; removal also clears their index entries. Documents can be attached to the whole collection or scoped to a single program.
See Chat & RAG System.
Administration
Administrative operations require an admin role. They cover:
- Collections & builds — create and manage collections; run extraction, import, and build (full or delta); watch build progress and logs; resume or stop a build; review build history; re-run auto-tagging.
- Source connections — define and manage typed connections to source platforms (IBM i, Oracle, and the z/OS registry), inspect the fields each connection type needs, and test connectivity. Stored credentials are not returned back to the caller.
- Users & roles — list and manage users, set each user's per-collection access, and reset passwords. SSO/OIDC (Azure AD, Okta, Google, or generic OIDC) can be configured for sign-in.
- Tags — manage business-concept tags and their assignments to programs and files; auto-generated tags from the build are preserved and can be curated.
- LLM & model configuration — manage the model role assignments and other configuration that govern the AI pipeline, review a read-only advisor that flags newer models against the current setup, and capture, apply, or revert named model presets. Severity for each analysis check can be tuned or turned off.
- Cost & usage reporting — review recorded token usage and cost, broken down by build, by query, and by model, and maintain the per-model pricing that costing draws on.
- Prompts — list and edit the prompt templates the pipeline uses.
- Logs & audit — read the security audit log, the change-plan generation log, the LLM chat prompt/response log, and the application and database-audit logs.
- Deployment — check version and update status, review deploy history and logs, and trigger a deploy.
- Compliance & audit export — query and export the tamper-evident audit trail and verify its hash chain, revoke a user's or all tokens, export a collection's data for portability, view a compliance/controls summary, and run retention and integrity maintenance.
See AI & Analysis Pipeline, Security Architecture, and Compliance.
Health & version
A public, unauthenticated health check reports liveness and readiness along with the running version and the status of dependencies such as the database and the source system.
MCP
In addition to REST, Afunana runs an authenticated MCP server so AI assistants can query the analyzed knowledge base directly. That surface is documentation and metadata only. See MCP Integration.