> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# repos.create()

> Create a Mesa repository, optionally with a default bookmark or upstream remote.

Create a repository in the current or specified organization.

**Required scope: `write`**

```ts theme={null}
const repo = await mesa.repos.create({ name: 'app' });

console.log(repo.name);
console.log(repo.head_change_id);
```

Create with an upstream Git remote:

```ts theme={null}
const repo = await mesa.repos.create({
  name: 'app',
  default_bookmark: 'main',
  upstream: {
    url: 'https://github.com/acme/app.git',
    auth: { kind: 'token', token: 'github_pat_...', token_username: 'bot' },
  },
});
```

## Options

<ParamField path="org" type="string | undefined">
  Organization override.
</ParamField>

<ParamField path="name" type="string | undefined">
  Repository name. If omitted, the API generates a name.
</ParamField>

<ParamField path="default_bookmark" type="string | undefined">
  Default bookmark name. Defaults to `main` when omitted.
</ParamField>

<ParamField path="tags" type="Record<string, string> | undefined">
  String key-value repository metadata.
</ParamField>

<ParamField path="upstream" type="object | undefined">
  Optional upstream Git remote to attach at create time. On create, omitting `auth` and passing `auth: null` both create a public upstream. Pass token or username/password auth to store credentials.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Repository ID.
</ResponseField>

<ResponseField name="org" type="string">
  Organization slug.
</ResponseField>

<ResponseField name="name" type="string">
  Repository name.
</ResponseField>

<ResponseField name="default_bookmark" type="string">
  Default bookmark name.
</ResponseField>

<ResponseField name="head_change_id" type="string">
  Current change ID at the default bookmark tip.
</ResponseField>

<ResponseField name="upstream" type="UpstreamConfig | null">
  Configured upstream remote, or null when no upstream is configured.
</ResponseField>

<ResponseField name="created_at" type="string">
  Creation time.
</ResponseField>

<ResponseField name="tags" type="Record<string, string>">
  Repository tags.
</ResponseField>

### UpstreamConfig

<ResponseField name="url" type="string">
  Upstream Git remote URL.
</ResponseField>

<ResponseField name="auth_kind" type="'token' | 'username_password' | null">
  Stored upstream authentication kind, or null when the upstream is public.
</ResponseField>