---
title: "Create repository"
method: POST
path: "/api/repos"
tags: ["Repositories"]
---

# Create repository

`POST /api/repos`

## Request

- Base URL: `https://hub.oxen.ai`
- URL: `https://hub.oxen.ai/api/repos`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/oxen/apis/oxen-server/docs/api/repos/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new repository, optionally with initial files via JSON or multipart form.

## Request body

- RepoNew: Only used between client and server for creating a new remote repository.
  - `description` string, nullable
  - `files` FileNew[], nullable
    - `contents` union, required
      - object
        - `Text` string, required
      - object
        - `Binary` integer[], required
    - `path` string, required
    - `user` User, required
      - `email` string, required
      - `name` string, required
  - `host` string, nullable
  - `is_public` boolean, nullable
  - `name` string, required: The name of the repository. When cloned locally, this is the name of the directory. This name uniquely identifies it in the namespace.
  - `namespace` string, required: The namespace that the repository lives in: dictates application-level repository ownership. A namespace can be e.g. a user, a team, or an entire organization. Namespaces must be unique.
  - `namespace_name` string, nullable: What the namespace is called, where `namespace` addresses it by UUID instead. Recorded as a hint beside the identity, ignored by a server that owns its own namespaces, and refused when it is not a valid namespace name.
  - `repo_name` string, nullable: What the repository is called, where `name` addresses it by UUID instead. Recorded as a hint beside the identity, ignored by a server that owns its own namespaces, and refused when it is not a valid repository name.
  - `repo_uuid` string, uuid, nullable: The immutable UUID to address the new repo's storage by. Supplied by an external control plane that owns repository identity; `None` leaves the choice to the server.
  - `root_commit` Commit
    - `author` string, required
    - `email` string, required
    - `id` string, required
    - `message` string, required
    - `parent_ids` string[], required
    - `timestamp` string, date-time, required
  - `scheme` string, nullable
  - `storage_kind` 'local' | 's3': Storage backend kind. Serializes as `"local"` / `"s3"` on the wire and on disk.

## Response `200`

Repository created

- RepositoryCreationResponse
  - `repository` RepositoryCreationView, required
    - `latest_commit` Commit
      - `author` string, required
      - `email` string, required
      - `id` string, required
      - `message` string, required
      - `parent_ids` string[], required
      - `timestamp` string, date-time, required
    - `min_version` string, nullable
    - `name` string, required
    - `namespace` string, required
    - `repo_uuid` string, uuid, nullable: The immutable UUID this repo's storage is addressed by. `None` for a repository whose identity backfill has not run.
    - `storage_kind` 'local' | 's3', required: Storage backend kind. Serializes as `"local"` / `"s3"` on the wire and on disk.
  - `status` string, required
  - `status_message` string, required

## Other responses

- `400`: Invalid payload
- `409`: Repository already exists

---

[API](https://skmtc.dev/oxen/apis/oxen-server.md) - [All operations](https://skmtc.dev/oxen/apis/oxen-server/llms.txt) - [OpenAPI document](https://skmtc.dev/oxen/apis/oxen-server/revisions/2ae578129949?raw)