> ## Documentation Index > Fetch the complete documentation index at: https://code.storage/docs/llms.txt > Use this file to discover all available pages before exploring further. # repos.create > Create a repository. 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. A new empty repository has no branch until its first commit. The first commit creates the branch that it targets, so the default branch exists only after a commit to it. Create is idempotent on the repository name. A new repository returns `201`. When the name already exists, the request returns `200`, and a copy copies nothing. When the name exists with a different upstream, the request returns `409`. The deprecated form of `base_repo`, with `provider` and `operation`, still works. Scope: `repo:write` on the repository. ## Create an empty repository Send only `repo_name`. The new repository uses `main` as its default branch, or the `default_branch` that you send. It has no branch until its first commit, so [`repos.branches.list`](https://code.storage/docs/api/repos/branches-list) returns an empty list. The first commit, for example from [`repos.commits.create`](https://code.storage/docs/api/repos/commit-pack), creates the branch that it targets. ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}} import { Pierre } from '@pierre/sdk'; // The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY. const pierre = new Pierre(); const repo = await pierre.repos.create({ repo_name: 'my-demo-repository' }); console.log(repo); ``` ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}} from pierre import Pierre # The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY. pierre = Pierre() repo = pierre.repos.create(repo_name="my-demo-repository") print(repo) ``` ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}} import ( "context" "fmt" pierre "github.com/pierrecomputer/sdk/go" ) ctx := context.Background() // The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY. client, err := pierre.NewClient() if err != nil { return err } repo, err := client.Repos.Create(ctx, pierre.ReposCreateParams{ RepoName: pierre.String("my-demo-repository"), }) if err != nil { return err } fmt.Println(repo) ``` ```bash CLI theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}} pierre repos create --repo-name my-demo-repository ``` The other samples of this page copy a repository with `base_repo`. ## OpenAPI ````yaml openapi.json POST /api/repos openapi: 3.1.0 info: description: >- The Code Storage HTTP API exposes repository management, Git reads, and write workflows over plain HTTPS. ## Authentication Send a signed JWT in the `Authorization: Bearer ` header on every request. - Organisation-scoped endpoints such as `GET /api/repos` require organisation scopes like `org:read` - Repository-scoped endpoints require a JWT whose `repo` claim names the target repository - Write operations require the relevant scope such as `git:write` or `repo:write` ## Pagination List endpoints use cursor-based pagination. - `cursor` is an opaque token returned by the previous response - `limit` defaults to `20` and is capped per endpoint - `has_more` tells you whether another request is available - `next_cursor` becomes the next `cursor` value ## Paths Preferred routes use the shorter `/api/...` form. Legacy `/api/v1/...` aliases remain documented where they are still supported and are marked as deprecated when a preferred route exists. ## Repository names in paths - Names containing `/` (or any other character that is not safe in a URL path segment) **must** be URL encoded so the value occupies a single path segment. For example, `pierre/example` becomes `pierre%2Fexample` and the request URL is `/api/repos/pierre%2Fexample/...`. - Plain names that contain only URL-safe characters can be sent as-is: `/api/repos/dotfiles/...`. - The server URL-decodes the value before resolving the repository, so double-encoding is not required. ## Errors Most endpoints return RFC 9457-compatible problem details under `application/problem+json`, with a legacy `error` field mirrored from `detail`. Each problem body has a stable, snake_case `code`. Branch on `code`, not on `detail`. The Error codes section lists the values. A `400 Bad Request` response for a request body can name the invalid fields in `invalid_params`. Each item has the dotted path of the field in `name`, for example `deployment.production_branch`, and the rule that the value breaks in `reason`. A `429 Too Many Requests` response carries the current IETF `RateLimit` service-limit field and `Retry-After`. `RateLimit` reports immediately available quota (`r`) and its effective window in seconds (`t`); `Retry-After` is the minimum delay and takes precedence. The gateway's capacity is dynamic, so it does not advertise a fixed `RateLimit-Policy` on successful responses. Streaming commit and note workflows may return operation-specific failure bodies so callers can inspect partial results, branch state, or workflow status without parsing generic error strings. ## Error codes Each problem body has a stable `code`. Each status has a generic code. A specific code replaces it when the caller must take a different action. New codes can be added. Treat an unknown code as the generic code for its status. Generic codes: `bad_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `request_timeout` (408), `conflict` (409), `precondition_failed` (412), `payload_too_large` (413), `unprocessable_entity` (422), `rate_limited` (429), `request_canceled` (499), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). Any other status uses its status text in snake_case. Specific codes: - `authentication_unavailable` (403): the server cannot verify credentials now; retry. - `insufficient_scope` (403): the token does not have a scope that the operation requires. - `repo_claim_missing` (400): the token has no `repo` claim. - `repo_name_mismatch` (400): the request `repo_name` does not match the token `repo` claim. - `route_not_found` (404): no API route matches the path. - `repository_not_found` (404): the repository does not exist or the token cannot access it. - `repository_deleted` (409): the repository is already deleted. - `repository_thawing` (409): the repository is being restored from cold storage; retry after `Retry-After`. - `sync_in_progress` (409): an upstream sync is in progress; retry. - `upstream_already_configured` (409): the repository already has an upstream. - `branch_not_found` (404): the branch does not exist. - `ref_not_found` (404): the ref or revision does not exist. - `merge_conflict` (409): the merge has file conflicts. - `ref_guard_failed` (409): a ref guard such as `expected_target_sha` does not match the ref; `guard` names it and `current_sha` is the commit of the ref. - `credential_not_found` (404): the Git credential does not exist. - `credential_exists` (409): the repository already has a Git credential. - `github_app_not_configured` (412): no GitHub App is set up for the organization, or the GitHub App of the repository has no usable private key. - `github_repository_inaccessible` (412, or the 4xx status from the upstream): GitHub does not give access to the upstream repository. - `hosting_not_enabled` (403): hosting is not enabled for the organization. - `hosting_project_not_found` (404): the repository has no hosting project. - `deployment_not_found` (404): the deployment does not exist. - `deployment_project_name_in_use` (409): another repository uses the hosting project name. - `idempotency_key_reused` (422): the idempotency key belongs to a different request. title: code.storage version: 1.0.0 servers: - description: Code Storage API host for your organization url: https://api.{org}.code.storage variables: org: default: your-org description: >- The subdomain of your API host. It is usually your organization name. The organization settings page in the dashboard shows your exact API host. security: [] tags: - description: >- Create, inspect, update, delete, and synchronise repositories, including upstream pull-sync and generic HTTPS Git credentials for non-GitHub upstreams. name: Repositories - description: Create, delete, list, and compare branches. name: Branches - description: >- Read commit metadata and diffs, or create commits without a local Git client. name: Commits - description: >- Read repository trees, file contents, archives, and server-side search results. name: Files - description: List, create, and delete Git tags. name: Tags - description: Attach and retrieve Git notes for commits or other Git objects. name: Notes - description: >- Read metadata about the Code Storage cluster that serves your organisation, such as its cloud location and inbound IP addresses. name: Organization paths: /api/repos: post: tags: - Repositories summary: Create Repo description: >- Create a repository. 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. A new empty repository has no branch until its first commit. The first commit creates the branch that it targets, so the default branch exists only after a commit to it. Create is idempotent on the repository name. A new repository returns `201`. When the name already exists, the request returns `200`, and a copy copies nothing. When the name exists with a different upstream, the request returns `409`. The deprecated form of `base_repo`, with `provider` and `operation`, still works. Scope: `repo:write` on the repository. operationId: repos-create parameters: - deprecated: true description: >- Deprecated: use the default_branch body field instead. Default branch for the new repository. When the body also has default_branch, the body value wins. in: query name: default_branch schema: type: string requestBody: content: application/json: example: base_repo: auth: token: SOURCE_REPO_READ_TOKEN name: pierre/sdk-documentation ref: main default_branch: feature-preview repo_name: pierre/docs-copy examples: copy: description: >- Create an independent repository from one commit of another Code Storage repository. summary: Copy value: base_repo: auth: token: SOURCE_REPO_READ_TOKEN name: pierre/sdk-documentation ref: main default_branch: feature-preview repo_name: pierre/docs-copy empty_repo: description: Create a new repository with an explicit default branch. summary: Empty repository value: default_branch: main repo_name: pierre/my-repo generic_git_sync: description: >- Mirror a repository from a generic HTTPS Git provider such as GitLab, Bitbucket, Gitea, or Forgejo. summary: Generic HTTPS Git sync value: default_branch: main repo_name: pierre/repo-name upstream: host: git.example.com name: repo-name owner: org-name provider: gitea public_github_sync: description: >- Mirror a public GitHub repository without a GitHub App installation. summary: Public GitHub sync value: default_branch: main repo_name: pierre/hello-world upstream: access: public name: hello-world owner: octocat provider: github schema: $ref: '#/components/schemas/ReposCreateRequest' description: >- Create an empty repository, a copy of a Code Storage repository (`base_repo`), or a repository that syncs from an external Git host (`upstream`). responses: '200': content: application/json: example: message: Repository 'pierre/sdk-documentation' already exists repo_name: pierre/sdk-documentation schema: $ref: '#/components/schemas/ReposCreateResponse' description: The repository already existed, and the request created nothing. '201': content: application/json: example: message: Repository 'pierre/sdk-documentation' created repo_name: pierre/sdk-documentation schema: $ref: '#/components/schemas/ReposCreateResponse' description: The request created the repository. '400': content: application/json: example: 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 schema: $ref: '#/components/schemas/ValidationProblemDetails' application/problem+json: example: 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 schema: $ref: '#/components/schemas/ValidationProblemDetails' description: >- The repository name was invalid or did not match the JWT repo claim, the request set both base_repo and upstream, or the source was invalid. `invalid_params` names each invalid field of the body. '401': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Conflict '429': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Too Many Requests headers: RateLimit: description: >- Current IETF service-limit field. `r=0` means no request is immediately available; `t` is the effective window in seconds before capacity is expected to return. schema: type: string Retry-After: description: >- Minimum delay before retrying, expressed as seconds or an HTTP date. This value takes precedence over the `RateLimit` effective window. schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Service Unavailable headers: Retry-After: description: Minimum delay in seconds before retrying. schema: type: string security: - bearerAuth: - repo:write x-codeSamples: - lang: typescript label: TypeScript source: |- import { Pierre } from '@pierre/sdk'; // The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY. const pierre = new Pierre(); const repo = await pierre.repos.create({ base_repo: { auth: { token: 'SOURCE_REPO_READ_TOKEN' }, name: 'pierre/sdk-documentation', ref: 'main' }, default_branch: 'feature-preview', repo_name: 'pierre/docs-copy', }); console.log(repo); - lang: python label: Python source: |- from pierre import Pierre # The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY. pierre = Pierre() repo = pierre.repos.create( base_repo={"auth": {"token": "SOURCE_REPO_READ_TOKEN"}, "name": "pierre/sdk-documentation", "ref": "main"}, default_branch="feature-preview", repo_name="pierre/docs-copy", ) print(repo) - lang: go label: Go source: "import (\n\t\"context\"\n\t\"fmt\"\n\n\tpierre \"github.com/pierrecomputer/sdk/go\"\n)\n\nctx := context.Background()\n// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.\nclient, err := pierre.NewClient()\nif err != nil {\n\treturn err\n}\nrepo, err := client.Repos.Create(ctx, pierre.ReposCreateParams{\n\tBaseRepo: pierre.Value(pierre.BaseRepo{Auth: pierre.Value(pierre.BaseRepoAuth{Token: pierre.String(\"SOURCE_REPO_READ_TOKEN\")}), Name: \"pierre/sdk-documentation\", Ref: pierre.String(\"main\")}),\n\tDefaultBranch: pierre.String(\"feature-preview\"),\n\tRepoName: pierre.String(\"pierre/docs-copy\"),\n})\nif err != nil {\n\treturn err\n}\nfmt.Println(repo)" - lang: cli label: CLI source: |- pierre repos create \ --base-repo '{"auth":{"token":"SOURCE_REPO_READ_TOKEN"},"name":"pierre/sdk-documentation","ref":"main"}' \ --default-branch feature-preview \ --repo-name pierre/docs-copy - lang: bash label: cURL source: |- curl -X POST "https://api.{org}.code.storage/api/repos" \ -H "Authorization: Bearer $PIERRE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "base_repo": { "auth": { "token": "SOURCE_REPO_READ_TOKEN" }, "name": "pierre/sdk-documentation", "ref": "main" }, "default_branch": "feature-preview", "repo_name": "pierre/docs-copy" }' components: schemas: ReposCreateRequest: additionalProperties: false description: >- Create-repository request body. It supplies the optional repository name, default branch, and Git Sync or fork configuration. properties: base_repo: $ref: '#/components/schemas/BaseRepo' description: >- Code Storage repository to copy once. The new repository keeps no link to it. Do not set it together with upstream. default_branch: description: >- Default branch for the new repository. When omitted, a copy takes the default branch of the source, a sync from GitHub takes the default branch of the GitHub repository, and any other repository uses main. An empty repository has no branch until its first commit, and a commit to this name creates the default branch. examples: - main type: string repo_name: description: Name of the new repository. It can contain a slash. examples: - pierre/sdk-documentation type: string upstream: $ref: '#/components/schemas/UpstreamConfig' description: >- External Git host to keep syncing from. The link lasts, and the repository can sync again. Do not set it together with base_repo. type: object ReposCreateResponse: additionalProperties: false description: Result of creating a repository, including its repository name. properties: http_url: deprecated: true description: 'Deprecated: use repo_name. Repository name or path, not a full URL.' examples: - pierre/sdk-documentation type: string message: description: >- Human-readable result: the repository was created, or it already exists. The status gives the same result: 201 or 200. examples: - Repository 'pierre/sdk-documentation' created type: string repo_id: deprecated: true description: 'Deprecated: use repo_name. Stable repository identifier.' examples: - repo_7f2b3d9 type: string repo_name: description: >- Repository name or path. It can contain a slash. It matches the JWT repo claim. examples: - pierre/sdk-documentation type: string required: - repo_id - repo_name - http_url - message type: object ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - properties: invalid_params: description: >- The invalid fields of the request body, one item for each field. The response leaves it out when the server cannot name the field, for example when the body is not valid JSON. items: $ref: '#/components/schemas/InvalidParam' type: array type: object description: >- Problem details of a request body that is not valid. `invalid_params` names each invalid field. type: object ProblemDetails: description: >- RFC 9457-compatible problem details payload describing the error response. properties: code: description: >- A stable, machine-readable error code in snake_case. Branch on `code`, not on `detail`. The API description lists the codes. type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status - code type: object BaseRepo: additionalProperties: false description: >- Code Storage repository that a new repository copies once. The deprecated form, with provider and operation, also describes a sync or a fork. properties: auth: $ref: '#/components/schemas/BaseRepoAuth' description: >- Authentication for the source repository. A copy requires auth.token. default_branch: deprecated: true description: 'Deprecated: use the top-level default_branch for a copy or a sync.' type: string name: description: >- Name of the Code Storage repository to copy. In the deprecated form, the repository name on the provider. examples: - templates/starter type: string operation: default: sync deprecated: true description: >- Deprecated: base_repo without provider is a copy, and upstream is a sync. In the deprecated form, sync (the default) or fork. enum: - sync - fork type: string owner: deprecated: true description: 'Deprecated: omit it for a copy, and use upstream.owner for a sync.' type: string provider: deprecated: true description: >- Deprecated: omit it for a copy, and use upstream for a sync. In the deprecated form, the provider of the source. enum: - github - gitlab - bitbucket - gitea - forgejo - codeberg - sr.ht - sourcehut - code.storage type: string ref: description: >- Branch, tag, or commit SHA to copy. It defaults to the HEAD of the source repository. examples: - main type: string sha: deprecated: true description: 'Deprecated: use ref, which accepts a commit SHA.' type: string upstream_host: deprecated: true description: 'Deprecated: use upstream.host.' type: string required: - name type: object UpstreamConfig: additionalProperties: false description: External Git host that a new repository keeps syncing from. properties: access: description: >- GitHub only. app (the default) reads through the GitHub App installation of the organization. public mirrors a public repository without an installation, and syncs only on request. enum: - app - public type: string host: description: >- Bare hostname of a self-hosted provider, such as gitlab.example.com. It defaults to the public host of the provider. type: string name: description: Repository name on the upstream provider. examples: - hello-world type: string owner: description: Repository owner or namespace on the upstream provider. examples: - octocat type: string provider: description: External Git host of the upstream repository. enum: - github - gitlab - bitbucket - gitea - forgejo - codeberg - sr.ht - sourcehut type: string required: - provider - owner - name type: object InvalidParam: additionalProperties: false description: One invalid field of the request body. properties: name: description: Dotted wire path of the field. examples: - deployment.production_branch type: string reason: description: The rule that the value breaks. examples: - exceeds 255 characters type: string required: - name - reason type: object BaseRepoAuth: additionalProperties: false description: >- Authentication used to access the base repository for sync or fork operations. properties: auth_type: deprecated: true description: >- Deprecated: use upstream.access for a public GitHub sync. A copy needs no auth_type. enum: - public - jwt type: string token: description: JWT with git:read on the source repository. A copy requires it. type: string type: object securitySchemes: bearerAuth: bearerFormat: JWT description: >- 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. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.