--- id: scope-create title: "Create a scope" description: "Create a new scope in an existing application." sidebar_label: "Create a scope" hide_title: true hide_table_of_contents: true api: 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 sidebar_class_name: "post api-method" info_path: docs/api/nullplatform-api custom_edit_url: null --- import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; Create a new scope in an existing application. ℹ️ **Note:**\n> \n>• **Agent-backed scopes:** Use `custom` to create a scope managed by your installed agent. This is the recommended and most flexible option for new scopes.\n>\n> • **Legacy scopes:** The other types are\n older, predefined scope types that depend on fixed infrastructure configurations.\n","x-deprecatedValues":["web_pool","web_pool_k8s","serverless"]},"provider":{"type":"string","enum":["your_provider_id","GOOGLE:WEB_POOL:GKE","AZURE:WEB_POOL:AKS","OCI:WEB_POOL:OKE","AWS:WEB_POOL:EKS","AWS:WEB_POOL:EC2INSTANCES","AWS:SERVERLESS:LAMBDA"],"default":"your_provider_id","example":"9e84a5c3-6c2e-4f15-90b0-1c67fd37f6e8","description":"Identifies the provider that powers this scope.\n\n> ℹ️ **Note:**\n>\n> • **Agent-backed scopes:** The **UUID** of the scope specification you created. This UUID is returned when you define a new scope specification and acts as your provider ID.\n>\n> • **Legacy scopes:** One of the predefined provider strings (for example,\n `\"AWS:WEB_POOL:EKS\"` or `\"GOOGLE:WEB_POOL:GKE\"`).","x-deprecatedValues":["GOOGLE:WEB_POOL:GKE","AZURE:WEB_POOL:AKS","OCI:WEB_POOL:OKE","AWS:WEB_POOL:EKS","AWS:WEB_POOL:EC2INSTANCES","AWS:SERVERLESS:LAMBDA"]},"application_id":{"type":"integer","example":2345,"description":"The ID of the application that owns this scope."},"requested_spec":{"example":{"memory_in_gb":2,"cpu_profile":"standard","local_storage_in_gb":8},"type":"object","description":"Defines the technical specifications for this scope (will be replaced by capabilities).","properties":{"memory_in_gb":{"type":"number","default":2,"example":2,"description":"The amount of memory allocated to this scope, measured in gigabytes (GB)."},"cpu_profile":{"type":"string","enum":["standard","intensive"],"example":"standard","description":"Defines the CPU profile for this scope."},"local_storage_in_gb":{"type":"number","default":2,"example":2,"description":"The amount of local storage available to this scope, measured in gigabytes (GB)."}},"title":"ScopeRequestedSpec"},"capabilities":{"type":"object","example":null,"description":"Optional features such as logging, auto scaling, and spot instances. See the [capabilities](/docs/scopes/capabilities) docs."},"messages":{"type":"object","example":null,"description":"Additional system messages related to the scope's status or configuration."},"external_created":{"type":"boolean","default":false,"description":"Indicates whether the scope was provisioned externally.\n`false` when provisioned by nullplatform; `true` if created externally (e.g., via Terraform/OpenTofu).\n"},"tier":{"example":"important","type":"string","description":"Defines the tier type of the scope.","enum":["testing","non_critical","important","critical"],"title":"ScopeTier"},"domain":{"type":"string","maxLength":255,"example":"billing-api-prod.nullapps.io","description":"A custom domain for the scope. Auto-generated if not provided."},"asset_name":{"type":"string","maxLength":60,"example":"main-asset","description":"The name of the asset."},"tags":{"type":"array","items":{"type":"string"},"example":["requires_deployment","high_priority"],"description":"Tags to associate with the scope."},"dimensions":{"type":"object","example":{"environment":"production"},"description":"Defines runtime configuration dimensions, such as environment or region, that apply to this scope."},"profiles":{"type":"array","items":{"type":"string"},"example":["environment_production"],"description":"NRN profiles to apply to this scope, independent of runtime configurations."},"instance_id":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","description":"A unique identifier for the runtime instance to associate with this scope. This value is typically set by the scope agent or cloud provider during provisioning."}},"title":"ScopeCreate"}}}}} > ℹ️ **Note:**\n>\n> • **Agent-backed scopes:** Use `custom` to create a scope managed by your installed agent.\n>\n> • **Legacy scopes:** The other types are\n older, predefined scope types that depend on fixed infrastructure configurations."},"provider":{"example":"9e84a5c3-6c2e-4f15-90b0-1c67fd37f6e8","default":"your_provider_id","type":"string","enum":["your_provider_id","GOOGLE:WEB_POOL:GKE","AZURE:WEB_POOL:AKS","OCI:WEB_POOL:OKE","AWS:WEB_POOL:EKS","AWS:WEB_POOL:EC2INSTANCES","AWS:SERVERLESS:LAMBDA"],"description":"Identifies the provider that powers this scope.\n\n> ℹ️ **Note:**\n> \n> • **Agent-backed scopes:** The **UUID** of the scope specification you created. This UUID is returned when you define a new scope specification and acts as your provider ID.\n>\n> • **Legacy scopes:** One of the predefined provider strings."},"status":{"example":"active","type":"string","description":"The status of the scope.","enum":["pending_approval","pending_hook","pending_approval_denied","pending","creating","recreating","active","updating","updating_approval","deleting","deleted","failed","stopping","stopped","cancelled"],"title":"ScopeStatus"},"slug":{"example":"billing-api","maxLength":60,"type":"string","description":"An application-wide unique slug for the scope."},"domain":{"example":"billing-api-prod.nullapps.io","maxLength":60,"type":"string","description":"An application-wide unique domain for the scope."},"application_id":{"example":2345,"type":"integer","description":"The ID of the application that owns this scope."},"requested_spec":{"example":{"memory_in_gb":2,"cpu_profile":"standard","local_storage_in_gb":8},"type":"object","description":"Defines the technical specifications for this scope (will be replaced by capabilities).","properties":{"memory_in_gb":{"type":"number","default":2,"example":2,"description":"The amount of memory allocated to this scope, measured in gigabytes (GB)."},"cpu_profile":{"type":"string","enum":["standard","intensive"],"example":"standard","description":"Defines the CPU profile for this scope."},"local_storage_in_gb":{"type":"number","default":2,"example":2,"description":"The amount of local storage available to this scope, measured in gigabytes (GB)."}},"title":"ScopeRequestedSpec"},"capabilities":{"type":"object","description":"Defines optional features such as logging, auto scaling, and spot instances. See the [capabilities](/docs/scopes/capabilities) documentation for details."},"messages":{"type":"object","description":"Additional system messages related to the scope's status or configuration.","example":null},"tier":{"example":"important","type":"string","description":"Defines the tier type of the scope.","enum":["testing","non_critical","important","critical"],"title":"ScopeTier"},"external_created":{"type":"boolean","description":"Indicates whether the scope was provisioned externally. `false` when provisioned by nullplatform, `true` if created externally (e.g., via Terraform)."},"tags":{"example":["requires_deployment","high_priority"],"type":"array","items":{"type":"string"},"description":"Tags associated with the scope."},"profiles":{"type":"array","items":{"type":"string"},"example":["environment_production"],"description":"NRN profiles that must be applied to this scope, independent of runtime configurations."},"dimensions":{"type":"object","example":{"environment":"production"},"description":"Defines runtime configuration dimensions, such as environment or region, that apply to this scope."},"runtime_configurations":{"type":"array","items":{"type":"integer"},"example":[1234,2345],"description":"Runtime configurations that apply to this scope based on its dimensions."},"domains":{"type":"array","description":"Array of custom domains associated with this scope.\n> It returns an empty array if no custom domains are assigned to the scope.\n","items":{"type":"object","required":["id","name","type"],"properties":{"id":{"type":"string","description":"The application-wide unique ID for the custom domain.","example":"e78a0d21-3c48-7421-81cd-203fe84b8e47"},"name":{"type":"string","description":"The name of the custom domain.","example":"api.crypto-inc.com"},"type":{"type":"string","description":"The type of the domain.","example":"scope"},"selector":{"type":"object","description":"The selector for the custom domain.","properties":{"organization_id":{"type":"string","description":"The organization ID.","example":"1"},"nrn":{"type":"string","description":"The NRN of entity.","example":"organization=1:account=2:namespace=3:application=4"},"scope_id":{"type":"string","description":"The scope ID that the custom domains is associated with..","example":"1234"}}},"status":{"type":"string","description":"The status of the domain.","enum":["active","pending"],"example":"active"},"created_at":{"type":"string","description":"The ISO-8601 UTC timestamp of when the custom domain was created.","format":"date-time","example":"2025-01-02T00:00:00Z"},"updated_at":{"type":"string","description":"The ISO-8601 UTC timestamp of when the custom domain was last updated.","format":"date-time","example":"2025-02-02T00:00:00Z"}},"title":"scopeDomainResponse"}},"instance_id":{"type":"string","description":"A unique identifier for the runtime instance associated with this scope.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"application_name":{"type":"string","description":"The name of the application that owns this scope.","example":"Billing Service"},"active_deployment":{"type":"object","nullable":true,"description":"The last finalized deployment for this scope, or `null` if no deployment has been completed."},"current_active_deployment":{"type":"object","nullable":true,"description":"The currently running deployment for this scope."},"in_progress_deployment":{"type":"object","nullable":true,"description":"A new deployment currently in progress, or `null` if none."},"stops_at":{"type":"string","nullable":true,"format":"date-time","description":"The ISO-8601 UTC timestamp when this scope is scheduled to stop, or `null` if not scheduled.","example":"2026-04-01T00:00:00Z"},"token_for_links":{"type":"string","description":"A JWT token for generating authenticated scope links. Only present for organizations with `generate_domain_token` enabled."},"created_at":{"type":"string","format":"date-time","description":"The ISO-8601 UTC timestamp of when the scope was created.","example":"2025-01-02T00:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The ISO-8601 UTC timestamp of when the scope was last updated.","example":"2025-06-15T12:30:00Z"},"metadata":{"type":"object","description":"The metadata loaded via the metadata catalog API.","example":{"key":"value"},"properties":{"key":{"type":"string","description":"The key of the metadata.","example":"key"},"value":{"type":"string","description":"The value of the metadata.","example":null},"additional_properties":{"type":"object","description":"Additional metadata properties, including schemas and tags.","properties":{"schemas":{"type":"array","description":"The JSON schemas of the metadata.","items":{"type":"object"}},"tags":{"type":"array","description":"Tags associated with the metadata.","items":{"type":"object","properties":{"key":{"type":"string","example":"key"},"value":{"type":"string","example":"value"}}}}}}},"title":"MetadataComponent"}},"title":"scope"}}}},"4XX":{"description":"Client error responses due to invalid input or missing parameters.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific client error (e.g., 400, 401, 403, 404).","example":400},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"bad_request"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Bad Request\", \"Unauthorized\").","example":"Bad Request"},"message":{"type":"string","description":"Additional details about the error.","example":"The request was malformed or contained invalid parameters."}}}}}},"5XX":{"description":"Server error responses indicating an issue on the API side.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific server error (e.g., 500, 502, 503).","example":500},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"internal_server_error"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Internal Server Error\", \"Service Unavailable\").","example":"Internal Server Error"},"message":{"type":"string","description":"Additional details about the error.","example":"An unexpected error occurred. Please try again later."}}}}}}}} >