Skip to main content
POST
/
api
/
repos
Create Repository
curl --request POST \
  --url https://api.example.com/api/repos \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "source_type": "<string>",
  "remote_url": "<string>",
  "default_branch": "<string>"
}
'
{
  "success": true,
  "data": {
    "id": "<string>",
    "user_id": "<string>",
    "org_id": "<string>",
    "name": "<string>",
    "source_type": "<string>",
    "remote_url": "<string>",
    "default_branch": "<string>",
    "last_commit_sha": "<string>",
    "oauth_connection_id": "<string>",
    "issue_auto_create_enabled": true,
    "issue_auto_create_min_severity": "<string>",
    "created_at": {},
    "updated_at": {}
  },
  "error": {
    "success": true,
    "code": 123,
    "message": "<string>"
  }
}

​
Authentication

This endpoint requires authentication. Include your session token in the request cookies or headers.

​
Request Body

​
name
string
required
Name of the repository. This will be displayed in the Heimdall dashboard.
​
source_type
string
Type of repository source. Defaults to git_url if not specified.
​
remote_url
string
Remote URL of the Git repository. Required for git_url source type. Optional for OAuth-based sources.
​
default_branch
string
Default branch to scan. If not specified, the repository’s default branch will be used (typically main or master).

​
Response

​
success
boolean
Indicates whether the request was successful.
​
data
object
The created repository object.

​
Example Request

​
Git URL Repository

curl -X POST https://api.heimdall.example.com/api/repos \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your_session_token" \
  -d '{
    "name": "my-web-app",
    "source_type": "git_url",
    "remote_url": "https://github.com/example/my-web-app.git",
    "default_branch": "main"
  }'

​
GitHub OAuth Repository

curl -X POST https://api.heimdall.example.com/api/repos \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your_session_token" \
  -d '{
    "name": "my-github-repo",
    "source_type": "github",
    "remote_url": "https://github.com/example/my-github-repo.git"
  }'

​
GitLab OAuth Repository

curl -X POST https://api.heimdall.example.com/api/repos \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your_session_token" \
  -d '{
    "name": "my-gitlab-project",
    "source_type": "gitlab",
    "remote_url": "https://gitlab.com/example/my-gitlab-project.git",
    "default_branch": "develop"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "01936d2f-8c4e-7890-b123-456789abcdef",
    "user_id": "01936d2e-1234-5678-9abc-def012345678",
    "org_id": null,
    "name": "my-web-app",
    "source_type": "git_url",
    "remote_url": "https://github.com/example/my-web-app.git",
    "default_branch": "main",
    "last_commit_sha": null,
    "oauth_connection_id": null,
    "issue_auto_create_enabled": false,
    "issue_auto_create_min_severity": "high",
    "created_at": "2026-03-12T10:30:00Z",
    "updated_at": "2026-03-12T10:30:00Z",
    "deleted_at": null
  }
}

​
Error Responses

​
error
object
Error information when the request fails.

​
401 Unauthorized

Returned when authentication credentials are missing or invalid. 
{
  "success": false,
  "code": 401,
  "message": "Authentication required"
}

​
500 Internal Server Error

Returned when the server encounters an error creating the repository. 
{
  "success": false,
  "code": 500,
  "message": "Failed to create repo: database connection error"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us