--- url: https://ibee.ai/docs/api-reference/container-registry/create-container-registry last_updated: 2026-10-25 --- > For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://ibee.ai/docs/llms.txt (full text of every page: https://ibee.ai/docs/llms-full.txt). For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ibee.ai/docs/_mcp/server. # Create registry POST https://api.ibee.ai/v1/container-registry/registries Content-Type: application/json Creates a registry with a storage plan (`billing_catalog.sku_code`). The registry service asks Billing whether the workspace may buy that plan and refuses with 403 `billing_resource_not_eligible` (and a `reason`) when it may not. Returns 201 when the registry is active, or 202 while provisioning finishes in the background; poll the registry until `observed_state` is `ACTIVE`. Requires scope: container-registry.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl -X POST "https://api.ibee.ai/v1/container-registry/registries?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"registry_name": "", "confirm_registry_name": "", "billing_catalog": {"sku_code": ""}}' ``` Reference: https://ibee.ai/docs/api-reference/container-registry/create-container-registry ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateContainerRegistryRequest. - `registry_name` (string, required) — Globally unique name; it cannot be changed or reused. - `confirm_registry_name` (string, required) — Must equal `registry_name`. - `billing_catalog` (ContainerRegistryBillingCatalog, required) — The storage plan to bill the registry against, identified by SKU. - `visibility` (enum, optional, default: PRIVATE) — - `PRIVATE`: pulls need an access token (default). - `PUBLIC`: anonymous pulls are allowed; egress is charged. - Allowed values: `PRIVATE`, `PUBLIC` - `acknowledge_public_egress_charges` (boolean, optional, default: false) — Required to be `true` when `visibility` is `PUBLIC`. - `security` (ContainerRegistrySecuritySettings, optional) — Security settings of a registry. ## Response ### 201 Registry created and active. - `registry_id` (string, required) — Unique ID of the registry. - `registry_name` (string, required) — Registry name. Images live at `registry.ibee.ai//:`. - `registry_kind` (enum, required) — Always `CUSTOMER` for registries created through the API. - Allowed values: `CUSTOMER` - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `visibility` (enum, required) — `PRIVATE` registries need a registry access token to pull. `PUBLIC` registries allow anonymous pulls, whose outbound bandwidth is billed to the workspace. Pushing always needs a token with push permission. - Allowed values: `PRIVATE`, `PUBLIC` - `security` (ContainerRegistrySecuritySettings, required) — Security settings of a registry. - `desired_state` (enum, required) — State requested by the caller. - `ACTIVE` - `DELETED` - Allowed values: `ACTIVE`, `DELETED` - `observed_state` (enum, required) — State the registry service has actually reached. - `PROVISIONING`: being created. - `UPDATING`: a change is being applied. - `DELETING`: being removed. - `ACTIVE`: ready. - `ERROR`: the last change failed. - `DELETED`: removed. - Allowed values: `PROVISIONING`, `UPDATING`, `DELETING`, `ACTIVE`, `ERROR`, `DELETED` - `generation` (integer, required) — Incremented by every accepted change. - `observed_generation` (integer, required) — The last generation applied; equal to `generation` when settled. - `created_at` (datetime, required) — When the registry was created (ISO 8601). - `updated_at` (datetime, required) — When the registry was last changed (ISO 8601). - `deleted_at` (datetime, required, nullable) — When deletion was requested (ISO 8601); null while the registry exists. ### 202 Registry accepted; provisioning continues in the background. - `registry_id` (string, required) — Unique ID of the registry. - `registry_name` (string, required) — Registry name. Images live at `registry.ibee.ai//:`. - `registry_kind` (enum, required) — Always `CUSTOMER` for registries created through the API. - Allowed values: `CUSTOMER` - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `visibility` (enum, required) — `PRIVATE` registries need a registry access token to pull. `PUBLIC` registries allow anonymous pulls, whose outbound bandwidth is billed to the workspace. Pushing always needs a token with push permission. - Allowed values: `PRIVATE`, `PUBLIC` - `security` (ContainerRegistrySecuritySettings, required) — Security settings of a registry. - `desired_state` (enum, required) — State requested by the caller. - `ACTIVE` - `DELETED` - Allowed values: `ACTIVE`, `DELETED` - `observed_state` (enum, required) — State the registry service has actually reached. - `PROVISIONING`: being created. - `UPDATING`: a change is being applied. - `DELETING`: being removed. - `ACTIVE`: ready. - `ERROR`: the last change failed. - `DELETED`: removed. - Allowed values: `PROVISIONING`, `UPDATING`, `DELETING`, `ACTIVE`, `ERROR`, `DELETED` - `generation` (integer, required) — Incremented by every accepted change. - `observed_generation` (integer, required) — The last generation applied; equal to `generation` when settled. - `created_at` (datetime, required) — When the registry was created (ISO 8601). - `updated_at` (datetime, required) — When the registry was last changed (ISO 8601). - `deleted_at` (datetime, required, nullable) — When deletion was requested (ISO 8601); null while the registry exists. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 422 Unprocessable Entity Error The registry service rejected a parameter or the body (`detail` lists the invalid fields), or the selected storage plan is not sold here (`detail.code`, for example `billing_sku_unavailable` or `billing_selection_not_found`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ContainerRegistryBillingCatalog The storage plan to bill the registry against, identified by SKU. - `sku_code` (string, required) — Storage plan SKU, for example `REGISTRY-STORAGE-250GB`. The service trims and upper-cases it, then requires `^[A-Z0-9][A-Z0-9_.-]*$`. Capacity and price come from Billing. ### ContainerRegistrySecuritySettings Security settings of a registry. - `vulnerability_pull_policy` (enum, optional) — `ALLOW` pulls every image. `BLOCK_` refuses pulls of images with a finding at or above that severity. - Allowed values: `ALLOW`, `BLOCK_CRITICAL`, `BLOCK_HIGH`, `BLOCK_MEDIUM`, `BLOCK_LOW` ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "registry_name": "", "confirm_registry_name": "", "billing_catalog": { "sku_code": "" } } ``` **Response** ```json { "registry_id": "4f2a9c1e-7b3d-4e8a-9f10-2c5d6e7f8a9b", "registry_name": "", "registry_kind": "CUSTOMER", "organization_id": "", "workspace_id": "", "visibility": "PRIVATE", "security": { "vulnerability_pull_policy": "ALLOW" }, "desired_state": "ACTIVE", "observed_state": "PROVISIONING", "generation": 1, "observed_generation": 1, "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "deleted_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/container-registry/registries" querystring = {"workspace_id":"710995"} payload = { "registry_name": "", "confirm_registry_name": "", "billing_catalog": { "sku_code": "" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/container-registry/registries?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"registry_name":"","confirm_registry_name":"","billing_catalog":{"sku_code":""}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/container-registry/registries?workspace_id=710995" payload := strings.NewReader("{\n \"registry_name\": \"\",\n \"confirm_registry_name\": \"\",\n \"billing_catalog\": {\n \"sku_code\": \"\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/container-registry/registries?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"registry_name\": \"\",\n \"confirm_registry_name\": \"\",\n \"billing_catalog\": {\n \"sku_code\": \"\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/container-registry/registries?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"registry_name\": \"\",\n \"confirm_registry_name\": \"\",\n \"billing_catalog\": {\n \"sku_code\": \"\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/container-registry/registries?workspace_id=710995', [ 'body' => '{ "registry_name": "", "confirm_registry_name": "", "billing_catalog": { "sku_code": "" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/container-registry/registries?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"registry_name\": \"\",\n \"confirm_registry_name\": \"\",\n \"billing_catalog\": {\n \"sku_code\": \"\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "registry_name": "", "confirm_registry_name": "", "billing_catalog": ["sku_code": ""] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/container-registry/registries?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```