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

# Create repository

> An account needs create permission on the project. A plugin installation's access token needs repositories:create; the repository then goes in the installation's project and joins the installation, and the response comes after the installation can mint tokens for it. An installation token cannot set clusterHost or mirrorClusterSlugs. An installation creates at most its plugin's daily limit of repositories in a rolling 24 hours (100 by default); past it the create answers 429 with Retry-After.

> [!WARNING]
>
> This endpoint is experimental. Its request and response formats may change.


## OpenAPI

````yaml https://us.console.entire.io/api/v1/openapi.json post /repos
openapi: 3.1.0
info:
  description: >-
    Entire control plane: identity, orgs, projects, repos, mirrors, service
    accounts.
  title: Entire Core API
  version: 1.0.0
servers:
  - url: https://us.console.entire.io/api/v1
security: []
tags:
  - name: identity
    x-group: Account
  - name: orgs
    x-group: Organizations
  - name: projects
    x-group: Projects
  - name: repos
    x-group: Repositories
  - name: clusters
    x-group: Clusters
paths:
  /repos:
    post:
      tags:
        - repos
      summary: Create repository
      description: >-
        An account needs create permission on the project. A plugin
        installation's access token needs repositories:create; the repository
        then goes in the installation's project and joins the installation, and
        the response comes after the installation can mint tokens for it. An
        installation token cannot set clusterHost or mirrorClusterSlugs. An
        installation creates at most its plugin's daily limit of repositories in
        a rolling 24 hours (100 by default); past it the create answers 429 with
        Retry-After.
      operationId: createRepo
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRepoInputBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedRepo'
          description: Created
          headers:
            Retry-After:
              schema:
                description: >-
                  Seconds to wait before reading the repo again. Present only
                  while state is "provisioning".
                type: string
            X-Entire-Commit-Token:
              schema:
                description: >-
                  Opaque token to pass as commitToken on the next repo resolve,
                  so this repo resolves immediately.
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Request
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
      security:
        - oauth2: []
        - oidc: []
        - bearerAuth: []
        - sessionAuth: []
        - automationToken: []
components:
  schemas:
    CreateRepoInputBody:
      additionalProperties: true
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - /api/v1/schemas/CreateRepoInputBody.json
          format: uri
          readOnly: true
          type: string
        clusterHost:
          description: >-
            Public host of the cluster to pin the repo to (e.g.
            royalcanin.partial.to); must be in the project's processing cell.
            Empty takes that cell's cluster.
          type: string
        mirrorClusterSlugs:
          description: >-
            Clusters to add native mirrors on once the repo is active. Core
            stores them with the create and retries each until its mirror
            exists.
          items:
            type: string
          maxItems: 16
          type: array
          uniqueItems: true
        name:
          minLength: 1
          type: string
        objectFormat:
          description: Hash format; defaults to sha1.
          enum:
            - sha1
            - sha256
          type: string
        projectId:
          description: >-
            Project to create the repo in. Required for an account. A plugin
            installation's token may omit it; the repo then goes in the
            installation's project, and any other project answers 404.
          pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          type: string
      required:
        - name
      type: object
    CreatedRepo:
      additionalProperties: true
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - /api/v1/schemas/CreatedRepo.json
          format: uri
          readOnly: true
          type: string
        candidate:
          $ref: '#/components/schemas/RepoCandidate'
        capabilities:
          $ref: '#/components/schemas/RepoCapabilities'
        clusterHost:
          type: string
        clusterSlug:
          type: string
        commitToken:
          deprecated: true
          description: 'Deprecated: read the X-Entire-Commit-Token response header instead.'
          type: string
        detachedAt:
          format: date-time
          type: string
        foreign:
          type: boolean
        fullName:
          type: string
        id:
          type: string
        jurisdiction:
          type: string
        lastPushedAt:
          format: date-time
          type: string
        mirrorClusterSlugs:
          description: >-
            Native-mirror clusters core stored with this create. Their status is
            on GET /repos/{repoId}/native-mirrors.
          items:
            type: string
          type: array
        mirrorSuspended:
          type: boolean
        mirrorSuspendedAt:
          type: string
        name:
          type: string
        nativeMirrors:
          description: >-
            Native mirrors this create queued, each pending with its reserved
            placementId. Their status is on GET /repos/{repoId}/native-mirrors.
          items:
            $ref: '#/components/schemas/NativeMirrorPlacement'
          type: array
        objectFormat:
          enum:
            - sha1
            - sha256
          type: string
        owningProjectId:
          type: string
        path:
          type: string
        placements:
          items:
            $ref: '#/components/schemas/RepoPlacement'
          type: array
        primaries:
          $ref: '#/components/schemas/RepoPrimaries'
        provider:
          enum:
            - github
            - entire
          type: string
        provisionAttempts:
          format: int64
          type: integer
        provisionReason:
          type: string
        repoGroupId:
          type: string
        repositoryId:
          description: >-
            Public repository id (repo_ followed by a ULID). Plugin installation
            routes, access tokens and webhooks use it.
          type: string
        state:
          description: >-
            Provisioning lifecycle. A mirror is active from creation, before its
            initial clone completes. A native primary reports deleting while a
            cascade delete removes its native mirrors; poll until 404.
          enum:
            - provisioning
            - active
            - failed
            - deleting
          type: string
        visibility:
          enum:
            - public
            - private
          type: string
      required:
        - id
        - owningProjectId
        - name
        - provider
        - capabilities
      type: object
    ErrorModel:
      additionalProperties: true
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - /api/v1/schemas/ErrorModel.json
          format: uri
          readOnly: true
          type: string
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    RepoCandidate:
      additionalProperties: true
      properties:
        access:
          enum:
            - read
            - write
            - admin
          type: string
        onboardable:
          type: boolean
      required:
        - access
        - onboardable
      type: object
    RepoCapabilities:
      additionalProperties: true
      properties:
        canManage:
          type: boolean
        canPull:
          type: boolean
        canPush:
          type: boolean
      required:
        - canManage
        - canPush
        - canPull
      type: object
    NativeMirrorPlacement:
      additionalProperties: true
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - /api/v1/schemas/NativeMirrorPlacement.json
          format: uri
          readOnly: true
          type: string
        attempts:
          format: int64
          type: integer
        clusterSlug:
          type: string
        createdAt:
          format: date-time
          type: string
        creationFailedAt:
          format: date-time
          type: string
        desiredState:
          enum:
            - active
            - deleted
          type: string
        failureCode:
          description: Stable code for why the region failed, when it did.
          type: string
        failureMessage:
          description: Why the region failed, as a sentence that is safe to show a user.
          type: string
        lastError:
          type: string
        nextRetryAt:
          format: date-time
          type: string
        placementId:
          type: string
        stage:
          enum:
            - pending
            - provisioned
            - registered
            - seeded
            - announced
          type: string
        status:
          enum:
            - processing
            - ready
            - failed
            - suspended
          type: string
      required:
        - placementId
        - clusterSlug
        - stage
        - status
        - desiredState
        - attempts
        - createdAt
      type: object
    RepoPlacement:
      additionalProperties: true
      properties:
        apiBaseUrl:
          type: string
        cell:
          type: string
        clusterSlug:
          type: string
        id:
          type: string
        jurisdiction:
          type: string
        mirror:
          type: boolean
        status:
          enum:
            - processing
            - ready
            - failed
            - suspended
          type: string
      required:
        - id
        - jurisdiction
        - cell
        - clusterSlug
        - mirror
        - status
      type: object
    RepoPrimaries:
      additionalProperties: true
      properties:
        data_primary:
          $ref: '#/components/schemas/ForgeRepoIdentity'
        git_data:
          type: string
        processing:
          type: string
        processing_primary:
          $ref: '#/components/schemas/ForgeRepoIdentity'
      required:
        - git_data
        - processing
        - data_primary
      type: object
    ErrorDetail:
      additionalProperties: true
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ForgeRepoIdentity:
      additionalProperties: true
      properties:
        forge:
          type: string
        repo_id:
          type: string
      required:
        - forge
        - repo_id
      type: object
  securitySchemes:
    oauth2:
      description: >-
        Authorization code flow with PKCE-S256. RFC 8628 device flow is also
        supported.
      flows:
        authorizationCode:
          authorizationUrl: /authorize
          scopes:
            offline_access: Request a refresh token.
            openid: Authenticate using OpenID Connect.
          tokenUrl: /oauth/token
      type: oauth2
    oidc:
      description: OpenID Connect discovery for browser and RFC 8628 device authentication.
      openIdConnectUrl: /.well-known/openid-configuration
      type: openIdConnect
    bearerAuth:
      bearerFormat: JWT
      description: Bearer access token.
      scheme: bearer
      type: http
    sessionAuth:
      description: Console session cookie issued by the browser login flow.
      in: cookie
      name: entire_session
      type: apiKey
    automationToken:
      bearerFormat: JWT
      description: >-
        A token this core issued to an automation, such as a plugin
        installation's.
      scheme: bearer
      type: http

````