Repositories API
Repository APIs expose Qarion-managed Git repositories for analyses, project workspaces, and the current user's personal saved-query repository. They let integrations inspect inventory, browse files, read commits and diffs, manage branches, request access, review merge requests, link repositories to governed assets, and publish repository content into Analyses.
All endpoints are mounted under /api/v1.0. Paths below omit that prefix for
readability.
Repository Types
| Type | Source | Notes |
|---|---|---|
analysis | Provisioned from an Analysis workspace. | Qarion owns protected main and develop; users work from imported user/<slug>/<topic> branches and publish through the Analysis review flow. |
project | Created from the repository inventory or an authoring workspace. | Supports branch creation, repository settings, access grants, merge requests, reviewers, review decisions, and publish-as-analysis imports. |
personal | Provisioned for the current user's saved queries. | Can be browsed through file, branch, commit, preview, download, and archive endpoints. Repository settings, governance links, and merge requests are not exposed for personal repositories. |
Repository responses include provider, provider_owner, provider_repo,
clone_url, web_url, default and develop branch names, sync_status,
last_error, effective_permissions, and related analysis or pending access
request metadata when available.
sync_status values include pending, synced, error, and conflicted.
Clients should surface last_error when status is error or conflicted.
Permissions
Repository access is evaluated per repository:
| Permission | Allows |
|---|---|
can_view | List the repository, browse files, read branches, commits, diffs, merge requests, and asset links. |
can_contribute | Upload repository attachments, create project merge requests, comment on merge-request diffs, and request reviewer updates where allowed. |
can_edit | Manage repository settings that do not require full admin access. |
can_admin | Manage access grants, archive/unarchive, delete project repositories, branch protection, branch deletion, and repository administration. |
Space managers and repository admins can grant explicit user or team access.
Project repositories can also expose a default space_member_access_level of
none, view, contribute, or edit.
Inventory And Lifecycle
Base path:
/engagement/spaces/{space_slug}/repositories
| Method | Endpoint | Description |
|---|---|---|
GET | /engagement/spaces/{space_slug}/repositories | List visible analysis and project repositories. Supports search, sync_status, and include_archived. |
POST | /engagement/spaces/{space_slug}/repositories | Create a project repository. |
GET | /engagement/spaces/{space_slug}/repositories/templates | List available project repository templates. |
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/access-requests | Create a workflow-backed access request for view, contribute, or edit. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/settings | Read repository settings and explicit grants. |
PATCH | /engagement/spaces/{space_slug}/repositories/{repository_id}/settings | Update maintainer, description, default space-member access, or merge-request approval rules. |
PUT | /engagement/spaces/{space_slug}/repositories/{repository_id}/access | Replace explicit user and team grants. |
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/archive | Archive a repository in Qarion. |
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/unarchive | Restore an archived repository. |
DELETE | /engagement/spaces/{space_slug}/repositories/{repository_id} | Soft-delete a project repository in Qarion. Provider repositories are not deleted. |
Create Project Repository
POST /engagement/spaces/acme/repositories
{
"name": "analytics-transformations",
"template_key": "dbt",
"description": "Reviewed dbt models for the analytics space",
"analysis_id": "optional-analysis-uuid"
}
template_key defaults to blank. Use the templates endpoint to discover
available keys and labels. analysis_id links the repository to an existing
analysis without turning it into an analysis-owned repository.
Settings And Access
PATCH /engagement/spaces/acme/repositories/{repository_id}/settings
{
"maintainer_id": "user-uuid",
"description": "Owned by analytics engineering",
"space_member_access_level": "view",
"merge_request_approval_rule": "any_approval",
"merge_request_require_non_author_approval": true
}
PUT /engagement/spaces/acme/repositories/{repository_id}/access
{
"grants": [
{
"principal_type": "team",
"principal_id": "team-uuid",
"access_level": "contribute"
}
]
}
merge_request_approval_rule is none, any_approval, or all_reviewers.
When merge_request_require_non_author_approval is true, the provider merge
request author cannot satisfy the approval requirement alone.
Branches
| Method | Endpoint | Description |
|---|---|---|
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/branches | List provider branches plus tracked analysis review refs. |
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/branches | Create or return a writable project branch. |
DELETE | /engagement/spaces/{space_slug}/repositories/{repository_id}/branches?branch={name} | Delete an unprotected branch. |
PUT | /engagement/spaces/{space_slug}/repositories/{repository_id}/branches/{branch_name}/protection | Protect or unprotect a branch. Slash-separated branch names are accepted in the path. |
{
"source_branch": "develop",
"branch_name": "user/ada/customer-risk-review",
"context_slug": "customer-risk-review"
}
If branch_name is omitted, Qarion generates a writable branch name from the
current user and context_slug. main and develop are Qarion-owned protected
branches and cannot be deleted.
Files, Previews, And Downloads
| Method | Endpoint | Description |
|---|---|---|
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/tree?ref={branch} | List the repository tree for a branch, tag, or SHA. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/contents?ref={branch}&path={path} | Read file metadata and text content when previewable. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/contents/download?ref={branch}&path={path} | Download one file. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/archive/download?ref={branch} | Download a branch archive. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/contents/image-preview?ref={branch}&path={path} | Return a bounded image preview for an image file. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/contents/presentation-preview?ref={branch}&path={path} | Return presentation text and preview metadata. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/contents/presentation-preview-images/{slide_number}?ref={branch}&path={path} | Return one rendered slide preview image. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/contents/word-preview?ref={branch}&path={path} | Return Word document text and preview metadata. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/contents/word-preview-images/{page_number}?ref={branch}&path={path} | Return one rendered Word page preview image. |
Text responses include content, encoding, truncated, download_url,
web_url, lfs_pointer, and lfs_resolved. If lfs_pointer is true and
lfs_resolved is false, the provider returned a Git LFS pointer instead of the
binary object.
Commits And Diffs
| Method | Endpoint | Description |
|---|---|---|
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/commits?ref={branch} | List commits. Supports limit and optional path. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/commits/{commit_sha}/diff | Read a commit diff. Supports optional path. |
Commit diffs include raw unified diff text plus rich_files for supported
asset types such as Markdown, notebooks, SQL, scripts, images, presentations,
spreadsheets, Word documents, and datasets. Large raw diffs are truncated; use
truncated to decide whether to ask the user to inspect the provider link.
Merge Requests And Review
| Method | Endpoint | Description |
|---|---|---|
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests | Create a project repository merge request and local Qarion review record. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests?state=open | List provider merge requests and linked review records. state is open, closed, or all. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref}/diff | Read a merge-request diff. Supports include_diff and include_rich_files. |
PATCH | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref} | Update project merge-request title, body, or change summary. |
PATCH | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref}/reviewers | Replace reviewers for the linked review record. |
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref}/review | Approve or request changes on the linked review record. |
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref}/merge | Merge a project repository merge request after review requirements are satisfied. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref}/comments | List diff comments. |
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref}/comments | Create a diff comment or reply. |
PATCH | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref}/comments/{comment_id} | Update a diff comment. |
DELETE | /engagement/spaces/{space_slug}/repositories/{repository_id}/merge-requests/{merge_request_ref}/comments/{comment_id} | Delete a diff comment. |
Analysis repositories expose provider merge requests in the repository browser, but new analysis merge requests and final publication are handled by the Analysis approval flow. Project repositories use the endpoints above directly.
Create Merge Request
{
"title": "Update retention model documentation",
"body": "Adds review notes and generated validation evidence.",
"source_branch": "user/ada/retention-model-review",
"target_branch": "develop"
}
Diff Comment
{
"content_markdown": "Can we add the data source owner here?",
"file_path": "models/retention.sql",
"side": "new",
"line_start": 42,
"line_end": 42,
"row_kind": "add",
"source_sha": "source-sha",
"target_sha": "target-sha"
}
Replies use parent_id and content_markdown; new top-level diff comments
must include file_path, side, line_start, and row_kind.
Attachments And Governance Links
| Method | Endpoint | Description |
|---|---|---|
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/attachments | Upload an image attachment for repository comments or review content. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/attachments/{attachment_id}/download | Download a repository attachment. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/asset-links | List links from the repository to governed assets. |
GET | /engagement/spaces/{space_slug}/repositories/{repository_id}/asset-link-candidates?target_type=data_product | Search link candidates. |
POST | /engagement/spaces/{space_slug}/repositories/{repository_id}/asset-links | Link a repository to a data product, contract, or quality check. |
PATCH | /engagement/spaces/{space_slug}/repositories/{repository_id}/asset-links/{link_id} | Update the relationship type. |
DELETE | /engagement/spaces/{space_slug}/repositories/{repository_id}/asset-links/{link_id} | Remove a governance link. |
target_type is data_product, data_contract, or quality_check.
relationship_type is creates, consumes, validates, deploys,
documents, maintains, or other.
Publish Repository Content As Analysis
POST /engagement/spaces/{space_slug}/repositories/{repository_id}/publish-analysis
{
"ref": "main",
"primary_path": "README.md",
"analysis_id": "optional-existing-analysis-uuid",
"title": "Retention model review",
"summary": "Imported from the analytics repository."
}
This endpoint imports supported project repository files into an Analysis. It
returns the Analysis detail, updated repository metadata, created_analysis,
imported_count, skipped_count, and per-path warnings. It is only supported
for project repositories.
Analysis Git Status
Analysis Git status endpoints live with the Analysis APIs:
| Method | Endpoint | Description |
|---|---|---|
GET | /engagement/spaces/{space_slug}/analyses/{analysis_id}/git | Get or provision the analysis repository and return tracked refs plus branch guidance. |
POST | /engagement/spaces/{space_slug}/analyses/{analysis_id}/git/sync | Re-sync the Analysis develop branch from Qarion state. |
GET | /engagement/spaces/{space_slug}/analyses/{analysis_id}/git/branches | List tracked imported branches for the Analysis. |
The status response includes branch guidance such as protected branches,
base_branch, suggested_branch_prefix, and suggested_branch_name.
Personal Repository And Git Credentials
Personal Git endpoints are mounted under /git:
| Method | Endpoint | Description |
|---|---|---|
GET | /git/me/personal-repository | Return the current user's personal repository and saved-query sync summary. |
POST | /git/me/personal-repository | Provision the current user's personal repository. |
POST | /git/me/personal-repository/saved-query-sync | Sync saved queries to the personal repository. |
GET | /git/me/personal-repository/saved-query-sync/events | List saved-query sync events. Supports limit and offset. |
POST | /git/me/personal-repository/saved-query-sync/repair | Repair personal saved-query sync state. |
GET | /git/me/git-credentials | List the current user's Git credentials. |
POST | /git/me/git-credentials | Create a Git credential and return the one-time token. |
DELETE | /git/me/git-credentials/{credential_id} | Revoke a Git credential. |
Credential scopes are read:repository and write:repository. Store the token
returned by credential creation immediately; subsequent reads only include
metadata such as token_name, token_prefix, scopes, and active/revoked state.
Admin Git Sync
Superadmin Analysis Git controls are mounted under /admin/analysis-git:
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/analysis-git/settings | Read non-secret Git provider settings, token/secret presence, repository counts, recent errors, and project repository defaults. |
PUT | /admin/analysis-git/repository-defaults | Update default project repository visibility and approval settings. |
POST | /admin/analysis-git/test-connection | Test the configured Git provider connection. |
POST | /admin/analysis-git/reconcile | Queue repository reconciliation for provisioned Analysis Git repositories. |
Deploy-time settings such as provider base URLs, admin token, webhook secret, service account, and callback URL remain environment or Helm configuration.
Error Notes
| Status | Meaning |
|---|---|
400 | Invalid branch, file path, merge-request payload, asset link target, or publish payload. |
403 | The caller lacks repository view, contribute, edit, admin, space, or superadmin permission. |
404 | Space, repository, branch, commit, merge request, file, attachment, asset link, or analysis was not found or is not visible. |
409 | Branch already exists and is protected, protected branches cannot be deleted, duplicate merge request exists, approval requirements are not satisfied, or analysis-only/project-only operation was used on the wrong repository type. |
422 | Office or presentation preview could not be rendered for the requested file/page/slide. |
502 | Qarion reached the Git provider, but the provider operation failed. |
503 | Git provider is not configured or temporarily unavailable. |