openapi: 3.1.0
info:
title: Freestyle Git API
version: 0.1.0
description: "Multi-tenant Git hosting for AI agents \u2014 repos, commits, branches, tags, trees, blobs, search across\
\ files/commits/diffs, GitHub Sync, repair jobs, triggers, and tarball/zip downloads."
contact:
name: Ben
email: [email protected]
license:
name: Closed Source
servers:
- url: https://api.freestyle.sh
description: Production
tags:
- name: Git
description: APIs for managing git repositories and accessing git objects like commits, trees, blobs, tags, and refs.
paths:
/git/v1/repo:
get:
tags:
- Git
summary: List Repositories
description: List repositories with metadata.
operationId: handle_list_repositories
parameters:
- name: limit
in: query
description: Maximum number of repositories to return
required: false
schema:
type: integer
format: int64
minimum: 0
- name: offset
in: query
description: Offset for the list of repositories
required: false
schema:
type: integer
format: int64
minimum: 0
- name: search
in: query
description: Search filter by repository name or ID
required: false
schema:
type: string
responses:
'200':
description: List of repositories
content:
application/json:
schema:
$ref: '#/components/schemas/ListRepositoriesSuccess'
'500':
description: 'Possible errors: Internal, GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
post:
tags:
- Git
summary: Create a Repository
description: 'Create a repository. Once the repository is created, it will also be created on the Git server.
The repository name must be unique within your account.
Once created, you can then push your code to this repository.
The repo will be available at `git.freestyle.sh/{repo-id}`
'
operationId: handle_create_repo
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type:
- string
- 'null'
description: 'This name is not visible to users, and is only accessible to you via API and in the
dashboard. Mostly useful for observability.'
public:
type: boolean
default: false
defaultBranch:
type:
- string
- 'null'
description: The default branch name for the repository. Defaults to "main" if not specified.
source:
$ref: '#/components/schemas/CreateRepoSource'
description: Fork from another Git repository. Cannot be used with `import`.
import:
$ref: '#/components/schemas/CreateRepoImport'
description: Import static content with an initial commit. Cannot be used with `source`.
required: true
responses:
'200':
description: Repository created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRepositoryResponseSuccess'
'403':
description: 'Error: GitRepoLimitExceeded'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: InternalServerError, GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/git/v1/repo/{repo_id}/default-branch:
get:
tags:
- Git
summary: Get Repository Default Branch
description: Get the default branch name for a repository.
operationId: handle_get_default_branch
parameters:
- name: repo_id
in: path
description: The repository ID
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetDefaultBranchResponse'
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: Internal, GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
put:
tags:
- Git
summary: Set Repository Default Branch
description: Set the default branch name for a repository. This will update the HEAD reference to point to the new default
branch.
operationId: handle_set_default_branch
parameters:
- name: repo_id
in: path
description: The repository ID
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetDefaultBranchRequest'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SetDefaultBranchResponse'
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: Internal, GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/git/v1/repo/{repo_id}/github-sync:
get:
tags:
- Git
summary: Get GitHub Sync Configuration
description: Get the GitHub sync configuration for a repository, if configured.
operationId: get_github_sync
parameters:
- name: repo_id
in: path
description: Repository ID
required: true
schema:
type: string
format: uuid
responses:
'200':
description: GitHub sync configuration
content:
application/json:
schema:
$ref: '#/components/schemas/GithubSyncConfigResponse'
'404':
description: Repository or sync configuration not found
'500':
description: Internal server error
post:
tags:
- Git
summary: Configure GitHub Sync for Repository
description: Configure GitHub synchronization for an existing Freestyle repository. This links your Freestyle repository
to a GitHub repository for automatic syncing. Requires the GitHub repository name in 'owner/repo' format.
operationId: configure_github_sync
parameters:
- name: repo_id
in: path
description: Repository ID
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigureGithubSyncRequest'
required: true
responses:
'200':
description: GitHub sync configured successfully
'400':
description: Bad request
'404':
description: Repository not found
'500':
description: Internal server error
delete:
tags:
- Git
summary: Remove GitHub Sync Configuration
description: Remove GitHub sync configuration from a repository. This stops automatic syncing but doesn't affect the
repository content.
operationId: remove_github_sync
parameters:
- name: repo_id
in: path
description: Repository ID
required: true
schema:
type: string
format: uuid
responses:
'200':
description: GitHub sync configuration removed successfully
'404':
description: Repository or sync configuration not found
'500':
description: Internal server error
/git/v1/repo/{repo_id}/visibility:
get:
tags:
- Git
summary: Get Repository Visibility
description: Get the visibility (public or private) for a repository.
operationId: handle_get_visibility
parameters:
- name: repo_id
in: path
description: The repository ID
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetVisibilityResponse'
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: Internal, GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
put:
tags:
- Git
summary: Set Repository Visibility
description: Set the visibility (public or private) for a repository.
operationId: handle_set_visibility
parameters:
- name: repo_id
in: path
description: The repository ID
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetVisibilityRequest'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SetVisibilityResponse'
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: Internal, GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/git/v1/repo/{repo}:
get:
tags:
- Git
summary: Get Repository Information
description: Retrieve information about a specific repository, including its ID, name, and default branch.
operationId: handle_get_repo_info
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
responses:
'200':
description: Repository information retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RepositoryInfoRaw'
'400':
description: Invalid request
'403':
description: Forbidden access to repository
'404':
description: Repository not found
'500':
description: Internal server error
delete:
tags:
- Git
summary: Delete a Repository
description: Delete a repository. This is irreversible, and will also delete the repository on the Git server.
operationId: handle_delete_repo
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
responses:
'200':
description: Repository deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteRepositorySuccess'
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: Internal, GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/git/v1/repo/{repo}/commits:
post:
tags:
- Git
summary: Create a Commit with Files
description: Create a commit from files with automatic tree building and branch updates. Supports text files (UTF-8),
binary files (base64), file deletions, and optimistic concurrency control via expectedSha. If the target branch does
not exist, it is created as an orphan branch with this commit as its root.
operationId: handle_create_commit
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommitRequest'
required: true
responses:
'200':
description: Commit created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommitResponse'
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Error: GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/git/v1/repo/{repo}/compare:
get:
tags:
- Git
summary: Compare Two Commits
description: Get the comparison between two commits in a repository
operationId: handle_compare_commits
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
format: uuid
- name: base
in: query
description: Base revision (commit SHA, branch name, tag, or any valid Git revision)
required: true
schema:
type: string
example: main
- name: head
in: query
description: Head revision (commit SHA, branch name, tag, or any valid Git revision)
required: true
schema:
type: string
example: dev
responses:
'200':
description: Comparison retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CommitComparison'
/git/v1/repo/{repo}/contents/{path}:
get:
tags:
- Git
summary: Get the Contents of a File or Directory
description: Get the contents of a file or directory in a repository
operationId: handle_get_contents
parameters:
- name: rev
in: query
description: The git revision (branch name, commit SHA, etc.). Defaults to HEAD.
required: false
schema:
type: string
- name: recursive
in: query
description: 'If true, directory entries include their descendants recursively.
Defaults to false (immediate children only).'
required: false
schema:
type: boolean
- name: repo
in: path
description: The repository ID.
required: true
schema:
type: string
format: uuid
- name: path
in: path
description: The path to the file or directory. Empty for root.
required: true
schema:
type:
- string
- 'null'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GitContents'
/git/v1/repo/{repo}/git/blobs/{hash}:
get:
tags:
- Git
summary: Get a Blob Object
description: Get a blob from the Git database. The contents will always be base64 encoded.
operationId: handle_get_blob
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
format: uuid
- name: hash
in: path
description: The object's hash
required: true
schema:
type: string
responses:
'200':
description: Blob retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BlobObject'
/git/v1/repo/{repo}/git/commits:
get:
tags:
- Git
summary: List Commits for a Repository
description: 'List commits with flexible filtering and pagination. Supports:
- Cursor-based pagination (recommended): Use `next_commit` from response with `until` (desc order) or `since` (asc
order)
- Commit ranges: Specify both `since` and `until` to get commits between them (like git''s `since..until`)
- Order control: `order=desc` (newest first, default) or `order=asc` (oldest first)
- Legacy offset pagination: Use `offset` param (deprecated, incompatible with since/until)
Requires repository visibility to be public or user to be the owner.'
operationId: handle_list_commits
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
format: uuid
- name: branch
in: query
description: Branch name (defaults to HEAD)
required: false
schema:
type:
- string
- 'null'
example: main
- name: limit
in: query
description: 'Maximum number of commits to return (default: 50, max: 500)'
required: false
schema:
type:
- integer
- 'null'
minimum: 0
example: '50'
- name: offset
in: query
description: 'Number of commits to skip (default: 0)'
required: false
deprecated: true
schema:
type:
- integer
- 'null'
minimum: 0
example: '0'
- name: order
in: query
description: 'Sort order: "desc" (newest first, default) or "asc" (oldest first)'
required: false
schema:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/CommitOrder'
- name: since
in: query
description: 'Start point (older commit) for filtering/pagination (commit SHA)
- When used alone with order=desc: Returns commits newer than this (exclusive). Use for "what''s new since X?"
- When used alone with order=asc: Starts from this commit (inclusive). Use with next_commit for pagination.
- When used with `until`: Defines the base of a range (like git''s A..B where this is A)'
required: false
schema:
type:
- string
- 'null'
example: abc123
- name: until
in: query
description: 'End point (newer commit) for filtering/pagination (commit SHA)
- When used alone with order=desc: Starts from this commit (inclusive). Use with next_commit for pagination.
- When used alone with order=asc: Returns commits up to and including this commit.
- When used with `since`: Defines the head of a range (like git''s A..B where this is B)
When both `since` and `until` are provided, `until` must be a descendant of `since`.'
required: false
schema:
type:
- string
- 'null'
example: def456
- name: disableTotalCount
in: query
description: 'If true, skip the exhaustive history walk used to compute `total`.
Defaults to false. When true, the `total` field is omitted from the
response. Use this for cursor-based pagination where `total` is unused.'
required: false
schema:
type:
- boolean
- 'null'
responses:
'200':
description: Commits retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CommitList'
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: Internal, GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
post:
tags:
- Git
summary: Create a Commit From Git Objects
description: Create a commit from tree and parent SHAs. This is a git object database operation for advanced use cases.
For file-based commits, use the high-level endpoint at /git/v1/repo/{repo}/commits.
operationId: handle_create_odb_commit
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOdbCommitRequest'
required: true
responses:
'200':
description: Commit created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOdbCommitResponse'
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Error: GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/git/v1/repo/{repo}/git/commits/{hash}:
get:
tags:
- Git
summary: Get a Commit Object
description: Get a commit from the Git database with detailed information.
operationId: handle_get_commit
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
format: uuid
- name: hash
in: path
description: The object's hash
required: true
schema:
type: string
responses:
'200':
description: Commit retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CommitObject'
/git/v1/repo/{repo}/git/refs/heads/:
get:
tags:
- Git
summary: List Branches in a Repo
description: Get a list of all branches in the Git repository. Returns branch names and their commit SHAs.
operationId: handle_list_branches
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Branches retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListBranchesResponse'
/git/v1/repo/{repo}/git/refs/heads/{*branch}:
post:
tags:
- Git
summary: Create a New Branch
description: Create a new branch in the Git repository. If sha is not provided, the branch is created from the default
branch HEAD.
operationId: handle_create_branch
parameters:
- name: repo
in: path
description: The repository id
required: true
schema:
type: string
format: uuid
- name: branch
in: path
description: The branch's name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBranchRequest'
required: true
responses:
'200':
description: Branch created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBranchResponse'
'400':
description: 'Error: BranchNameEmpty'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'403':
description: 'Error: Forbidden'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Error: GitClient'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/git/v1/repo/{repo}/git/refs/heads/
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/freestyle-sh/refs/heads/main/openapi/freestyle-git-api-openapi.yml