> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Create a repository > A repository must exist before anything can be pushed to it. There is no create-on-push: a repository carries quota, resource tags, a tag-mutability setting, and possibly a resource policy, and conjuring one from a typo in a `docker push` would produce an unlabelled, unpoliced repository nobody meant to make. The name is immutable. It is the CRN every IAM policy names and the reference every deployment manifest pulls, so renaming would silently invalidate both. ## OpenAPI ````yaml /api-reference/specs/registry.yaml post /v1/repositories openapi: 3.0.3 info: title: Basaltic Registry API version: 1.0.0 description: | Private container image registries, backed by Ceph. **This spec documents the control plane, not the pull path.** The registry serves two protocols on one host. Everything below is the `/v1` REST surface — repositories, images, lifecycle policies, resource policies — authenticated with a request signature or a console session, like every other Basaltic API. Separately, `/v2` implements the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec) v1.1, which is what `docker`, `podman`, `buildah`, `crane`, `skopeo`, and every Kubernetes node's container runtime speak. That surface is not described here because it is not ours to describe: its paths, status codes, headers, and error codes are fixed by the spec, and a client that finds anything else fails. **Getting a docker credential.** `POST /v1/authorization-token` returns a short-lived password. Feed it to `docker login`; the daemon then exchanges it at `/v2/token` for per-repository bearer tokens on its own, which is where the actual authorization decision is made. The login credential carries no authority of its own — revoking a policy takes effect within one bearer token's lifetime (five minutes) rather than at the end of a twelve-hour login. ``` basaltic registry get-login-password --region sa-saopaulo-1 \ | docker login --username basaltic --password-stdin registry.sa-saopaulo-1.basaltic.sh docker push registry.sa-saopaulo-1.basaltic.sh/my-account/api:v1 ``` **The account handle is part of the image reference.** A region serves one registry host, so an image lives at `registry..//:`. That first path component is the only thing separating two tenants' `api` repositories, which is why every repository response includes a ready-made `uri` rather than leaving clients to assemble one. **Everything except a tag is immutable.** A blob is named by the sha256 of its bytes and a manifest by the sha256 of its own JSON, so pushing the same content twice is a no-op the client detects before it uploads a byte. A tag is the one mutable pointer — and a repository may forbid even that, with `tag_mutability: immutable`, so a deployed digest cannot be swapped under a running fleet. **Deleting by digest and deleting by tag are different.** Removing a digest removes the manifest and every tag pointing at it. Removing a tag leaves the manifest in place, untagged: another tag may still name it, and `docker rmi` of one tag must not destroy an image someone else is pulling by another. Untagged manifests are what the `untagged` lifecycle rule exists to sweep. **Layers are shared and counted once.** Blobs are deduplicated across every repository in an account, so a repository's `size_bytes` is the sum of the distinct blobs its manifests reference — not the sum of its images' sizes, which would count every shared base layer once per image. Deleting an image does not immediately free space: whether a layer is still needed is a question about every other repository in the account, and the answer comes from a background sweep. **Sharing a repository.** A repository is private to its account until you attach a resource policy. `PUT /v1/repositories/{id}/policy` is how another account — or, with principal `*`, the public — is granted pull access. Cross-account access requires BOTH the resource policy and the caller's own IAM policy to allow it, so one tenant cannot grant another tenant's employee more than that employee's organization permits. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://registry.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] tags: - name: Authorization description: The credential `docker login` consumes - name: Repositories description: Repository lifecycle and settings, and the images and tags in one - name: Policies description: Resource policies and lifecycle policies - name: Encryption description: At-rest encryption of layer bytes - name: Pull-through cache description: Mirroring an upstream registry's images into a namespace of your own paths: /v1/repositories: post: tags: - Repositories summary: Create a repository description: | A repository must exist before anything can be pushed to it. There is no create-on-push: a repository carries quota, resource tags, a tag-mutability setting, and possibly a resource policy, and conjuring one from a typo in a `docker push` would produce an unlabelled, unpoliced repository nobody meant to make. The name is immutable. It is the CRN every IAM policy names and the reference every deployment manifest pulls, so renaming would silently invalidate both. operationId: createRepository parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRepositoryRequest' responses: '201': description: Repository created. content: application/json: schema: $ref: '#/components/schemas/RepositoryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: A repository with this name already exists in the account. content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateRepositoryRequest: type: object properties: name: type: string maxLength: 191 example: team/api tag_mutability: type: string enum: - mutable - immutable default: mutable deletion_protection: type: boolean default: false tags: type: object additionalProperties: type: string required: - name RepositoryResponse: type: object properties: repository: $ref: '#/components/schemas/Repository' push_commands: type: array items: type: string description: | The login/build/push sequence for this repository. Rendered server-side because the login username, the endpoint, and the account handle's position in the reference all come from service configuration. example: - >- basaltic registry get-login-password --region sa-saopaulo-1 | docker login --username basaltic --password-stdin registry.sa-saopaulo-1.basaltic.sh - >- docker build -t registry.sa-saopaulo-1.basaltic.sh/my-account/team/api:latest . - >- docker push registry.sa-saopaulo-1.basaltic.sh/my-account/team/api:latest required: - repository Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 Repository: type: object properties: id: type: string format: uuid example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d crn: type: string description: | The IAM resource name. Built from the repository NAME, not its id, so a policy naming a repository keeps applying after a delete and re-create under the same name — which matters here more than elsewhere, because the name is what every deployment manifest pulls. example: crn:registry:sa-saopaulo-1:my-account:repository/team/api name: type: string maxLength: 191 description: | Lowercase alphanumeric path components separated by a single period, one or two underscores, or hyphens, joined by slashes. This is the OCI grammar — anything else is not pushable, so a laxer rule would only produce repositories nobody can use. example: team/api uri: type: string description: | The pullable reference prefix. Returned rather than left for clients to assemble: the account handle's position in the path is the only thing separating two tenants' repositories of the same name. example: registry.sa-saopaulo-1.basaltic.sh/my-account/team/api tag_mutability: type: string enum: - mutable - immutable description: | `immutable` refuses to move a tag that already resolves, so a deployed digest cannot be swapped under a running fleet. Pushing a tag that does not exist yet still works — the guarantee is that a tag never changes meaning, not that the tag set is frozen. A repeat push of the identical manifest is always allowed. example: mutable deletion_protection: type: boolean description: | Refuses `DeleteRepository` while set, even for an empty repository and even with `force`. example: false tags: type: object additionalProperties: type: string description: >- AWS-style resource tags. Feed the `basalt:ResourceTag/*` policy conditions. example: env: prod team: platform stats: $ref: '#/components/schemas/RepositoryStats' created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - crn - name - uri - tag_mutability - deletion_protection - created_at - updated_at RepositoryStats: type: object properties: image_count: type: integer example: 42 tag_count: type: integer example: 17 size_bytes: type: integer format: int64 description: | The sum of the DISTINCT blobs this repository's manifests reference. Not the sum of its images' sizes: ten tags of one image share their layers, and adding the per-image figures would report ten times the space occupied. example: 1073741824 last_pushed_at: type: string format: date-time nullable: true description: Null for a repository that has never received an image. responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 UnprocessableEntity: description: | The request is well-formed but cannot be processed as sent. On the operations that accept `Idempotency-Key` this is the key-reuse case: the key was first seen with a different request payload, so replaying the stored outcome would answer a question the caller did not ask. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````