Prompts
GitHub Prompt
Prompts kept as files in a GitHub repository and synced to Multi-Router on every push.
A GitHub prompt is a .md or .json file in a GitHub repository that Multi-Router tracks. The repository stays the source of truth: prompt changes go through the team's usual review in pull requests, and when a commit that changes a tracked file lands on the tracked branch, Multi-Router picks up the new content. GitHub prompts are read-only in Multi-Router, their revisions are commits, and a router can be pinned to any commit of the file.
A repository is connected to Multi-Router through a GitHub connection and a prompt repo:
| Object | Id | Description |
|---|---|---|
| GitHub connection | The GitHub login | A GitHub organization or personal account where the Multi-Router GitHub App is installed and claimed by the Multi-Router organization. |
| Prompt repo | pr_ | One repository and branch tracked as a prompt source, such as example-co/prompts on main. |
| GitHub prompt | pf_ | One tracked file in a prompt repo, such as prompts/support-triage.md. |
Connecting a GitHub organization
A GitHub connection gives Multi-Router read access to the repositories the Multi-Router GitHub App is installed on. Connecting and disconnecting a GitHub organization requires an organization admin, and is done in the dashboard:
- On the Prompts page, select New Prompt and choose Connect new GitHub org.
- On GitHub, choose the organization or personal account, choose which repositories the App can read, and approve the install.
- GitHub returns to the Prompts page, which claims the installation for the organization and opens the form to connect a repository.
Manage GitHub orgs on the same menu lists the connected organizations, with Connect, Disconnect, Authorize GitHub and Re-authorize. The panel shows which GitHub user it is listing installations for, and an installation is claimed by an admin who has used Authorize GitHub and can see the installation on GitHub. A GitHub installation can be claimed by more than one Multi-Router organization. Disconnecting a GitHub organization stops its prompt repos from syncing: routers that track latest keep the content last synced, and routers pinned to an earlier commit return an error until the organization is connected again.
Connecting a repository
A prompt repo tracks one branch of one repository. In the dashboard:
- Select New Prompt and choose Connect repo from the connected GitHub organization.
- Search for and choose the repository, then choose the branch.
- Choose the
.mdand.jsonfiles to track, and connect.
Multi-Router fetches each chosen file at once, and each file appears on the Prompts page as a GitHub prompt. A repository and branch are connected once per organization; to track another branch of the same repository, connect it as a second prompt repo. Through the API, a prompt repo is connected with POST /v1/prompt-repos. Connect the repository's GitHub organization in the dashboard first; until it is connected, each file of the prompt repo shows the status error with the message github account not connected.
Tracked files
A tracked file is a path in the prompt repo that Multi-Router keeps in sync. A file path is relative to the repository root, up to 512 characters, ends in .md or .json in any letter case, and starts with a file or folder name, with every segment other than . or ... A .md file is a text prompt whose content is the file's text, and a .json file is a chat prompt whose content is a JSON array of messages. See Prompt Type.
On the prompt's page, Add files opens a list of the branch's files with the tracked files checked and locked, and Stop tracking removes the file from Multi-Router while leaving it in the repository. Through the API, POST /v1/prompt-repos/{id}/files with a path tracks one file, and DELETE /v1/prompt-repos/{id}/files?path= stops tracking it. GET /v1/prompt-repos/{id}/files lists the tracked files with their prompt ids and sync status. A file that routers are bound to stays tracked until those routers are unbound, and the request is refused with prompt_in_use.
Syncing
Syncing is how a commit on GitHub reaches Multi-Router. When a push lands on a tracked branch, GitHub notifies Multi-Router, which fetches each tracked file the push added, changed or removed, in every organization and prompt repo that tracks that branch. Files the push did not touch keep their current content. A router that tracks latest uses the new content from its next request, usually within seconds of the push.
A file is fetched when it is first tracked, when it is added again, and on each push that changes it. Each tracked file has a status:
| Status | Meaning |
|---|---|
pending | The file is tracked and its first fetch has not finished. |
synced | The file was fetched and its content is current with the branch. |
error | The last fetch failed. The error message says why. |
When a fetch fails for a temporary reason, such as a GitHub outage or rate limit, the file keeps serving the content from its last successful fetch until the next push syncs it. When the file has been removed from the branch, or its content is not a valid prompt, routers bound to it return an error until the file is fixed and pushed again. The error message is one of:
| Error message | Cause |
|---|---|
removed upstream | A push deleted the file from the tracked branch. |
invalid chat body: … | A .json file is not a valid chat prompt. The message describes the problem. |
| github account not connected | The repository's GitHub organization is no longer connected. |
github: unauthorized | The GitHub App no longer has access to the repository. |
github: not found | The repository, branch or file was not found. |
github: rate limited | GitHub limited the number of requests. |
github: server error | GitHub returned a server error. |
github: timed out | GitHub did not respond in time. |
github: response too large | The file is larger than the prompt size limit. |
github: network error | GitHub could not be reached. |
github: api error | GitHub returned an unexpected error. |
github: malformed response | GitHub returned a response Multi-Router could not read. |
github: credentials misconfigured | The GitHub integration for this Multi-Router installation is set up incorrectly. |
Revisions
The revisions of a GitHub prompt are the commits on the tracked branch that changed the file, newest first, each with its commit SHA, commit message and date. The prompt's History tab lists them, and a router can be pinned to any of them by its SHA, written in full or shortened to at least 7 characters. The API reads them with GET /v1/prompts/{id}/versions and GET /v1/prompts/{id}/versions/{sha}, which read the history from GitHub when called, and return up to the 100 most recent revisions. Reading a single commit returns its version and body. The commits of the whole repository, or of one tracked file, are listed with GET /v1/prompt-repos/{id}/commits. When GitHub cannot be read, the revision endpoints return 502 with github_unavailable, when the GitHub organization is not connected, or github_error, when the fetch fails.
The GitHub prompt page
A GitHub prompt's page shows the file's content with a note that it is read-only and changes by pushing to GitHub, and a History tab with its commits. A file switcher moves between the files of the same prompt repo. The page offers Add files, Stop tracking and Disconnect, which disconnects the whole prompt repo.
Disconnecting a repository
Disconnecting a prompt repo stops tracking all of its files, and their GitHub prompts are removed from Multi-Router. The repository on GitHub is unchanged. A prompt repo with files that routers are bound to stays connected until those routers are unbound, and the request is refused with prompt_in_use. Through the API, a prompt repo is disconnected with DELETE /v1/prompt-repos/{id}, which returns the number of files removed:
GitHub connections in the API
GitHub connections are read and removed through the API, and created in the dashboard because installing the GitHub App takes place on GitHub.
| Endpoint | Description |
|---|---|
GET /v1/github/connections | Lists the connected GitHub organizations, each with its login, installation_id and connected_at. |
GET /v1/github/connections/{login} | Reads one connection. |
DELETE /v1/github/connections/{login} | Disconnects a GitHub organization. Its prompt repos stay and stop syncing. Accepts dry_run. |
Errors
Connecting repositories and tracking files return the following errors:
| Error | Status | Cause |
|---|---|---|
prompt_repo_exists | 409 | The organization already tracks this repository and branch. |
invalid_field | 400 | A file path, repository name or branch is not valid. |
prompt_repo_not_found | 404 | No prompt repo with that id exists in the organization. |
file_not_found | 404 | The prompt repo does not track that file. |
github_not_connected | 424 | The repository's GitHub organization is not connected. |
github_repo_not_found | 404 | The connected organization cannot find the repository or branch. |
connection_not_found | 404 | No connected GitHub organization has that login. |
prompt_in_use | 409 | Routers are bound to a file being untracked or disconnected. The message lists the routers. |
source_read_only | 409 | An edit or delete names a GitHub prompt through the prompt endpoints. |
rate_limited | 429 | The organization made more than 60 requests in a minute that check GitHub. |
invalid_body | 400 | A required field is missing, or the body has the wrong shape. |
invalid_json | 400 | The request body is not valid JSON. |
version_conflict | 412 | The If-Match ETag is stale. The response carries the current prompt repo. |
use_sub_collection | 400 | A PATCH sends files or tags, which change through their own endpoints. The valid field of the error lists the endpoint path template, such as /v1/prompt-repos/{id}/files; {id} is not replaced with the object id. |
github_not_configured | 503 | The GitHub integration is not set up for this Multi-Router installation. |