Repo: Create

Create a repository. The JWT repo claim supplies the repository name. The optional repo_name body field must equal that claim.

A repository starts empty or from a source. base_repo is a one-time copy of a Code Storage repository; upstream is a lasting link to an external Git host. A copy takes the history of one commit (base_repo.ref, or the source HEAD) into one branch, and keeps no link to its source. A sync keeps its upstream, and the repository can sync from it again. Set at most one of the two.

The deprecated form of base_repo, with provider and operation, still works.

JWT claims

Required scopes: repo:write
Requires per repo scope: Yes

POST

api

repos

curl --request POST \
  --url https://api.{org}.code.storage/api/repos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "base_repo": {
    "auth": {
      "token": "SOURCE_REPO_READ_TOKEN"
    },
    "name": "pierre/sdk-documentation",
    "ref": "main"
  },
  "default_branch": "feature-preview",
  "repo_name": "pierre/docs-copy"
}
'

{
  "http_url": "pierre/sdk-documentation",
  "message": "repository created",
  "repo_id": "repo_7f2b3d9",
  "repo_name": "pierre/sdk-documentation"
}

{
  "code": "bad_request",
  "detail": "base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host.",
  "error": "base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host.",
  "instance": "/api/repos",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

Authorizations

Authorization

string

header

required

JWT bearer token signed with your organization's registered signing key. There is no OAuth authorization server; you mint tokens yourself and the token's scopes claim carries the granted permission scopes. Public scopes: git:read (read repository contents), git:write (write branches, commits, tags, and notes), repo:write (create and manage repositories), org:read (list an organization's repositories). Each operation's security requirement names the scopes it requires. See https://code.storage/docs/getting-started/authentication for how to mint tokens.

Query Parameters

default_branch

string

Optional default branch override. When present, it is used if the request body does not already specify one.

Body

application/json

Create an empty repository, a copy of a Code Storage repository (base_repo), or a repository that syncs from an external Git host (upstream).

Create-repository request body. The JWT repo claim supplies the repository name. The optional repo_name field must equal that claim. The body also supplies optional default-branch and Git Sync or fork configuration.

base_repo

object

Code Storage repository to copy once. The new repository keeps no link to it. Do not set it together with upstream.

Show child attributes

default_branch

string

Default branch for the new repository. Defaults to main when omitted.

Example:

"main"

repo_name

string

Name of the new repository. It can contain a slash. When present, it must equal the JWT repo claim. When omitted, the repo claim supplies the name.

Example:

"pierre/sdk-documentation"

upstream

object

External Git host to keep syncing from. The link lasts, and the repository can sync again. Do not set it together with base_repo.

Show child attributes

Response

Repository created successfully.

Result of creating a repository, including the assigned internal repository ID and the repository URL path.

http_url

string

required

deprecated

Deprecated: use repo_name. Repository name or path, not a full URL.

Example:

"pierre/sdk-documentation"

message

string

required

High-level creation result.

Example:

"repository created"

repo_id

string

required

deprecated

Deprecated: use repo_name. Stable repository identifier.

Example:

"repo_7f2b3d9"

repo_name

string

required

Repository name or path. It can contain a slash. It matches the JWT repo claim.

Example:

"pierre/sdk-documentation"

curl --request POST \
  --url https://api.{org}.code.storage/api/repos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "base_repo": {
    "auth": {
      "token": "SOURCE_REPO_READ_TOKEN"
    },
    "name": "pierre/sdk-documentation",
    "ref": "main"
  },
  "default_branch": "feature-preview",
  "repo_name": "pierre/docs-copy"
}
'

{
  "http_url": "pierre/sdk-documentation",
  "message": "repository created",
  "repo_id": "repo_7f2b3d9",
  "repo_name": "pierre/sdk-documentation"
}

{
  "code": "bad_request",
  "detail": "base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host.",
  "error": "base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host.",
  "instance": "/api/repos",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

Getting Started

Platform

Workflows

Libraries

API Reference

Repo: Create

JWT claims

Authorizations

Query Parameters

Body

Response