Account5

Action36

Action Item12

Action Item Category5

Action Item Comment2

Agent3

Announcements6

API keys5

Application4

Approval6

Artifact7

Asset4

Authentication1

Build4

Catalog instance (multiple keys)3

Catalog instance (single key)4

Catalog specification5

Category2

Channel5

Checklist6

Custom domain5

Deployment4

Deployment group4

Deployment strategy5

Dimension5

Dimension value1

Dimension Value4

Entity hook8

Event3

Inbox rules12

Link12

Log config4

Log specification5

Log template4

Namespace5

NRN5

Organization2

Package10

Parameter11

Personal access tokens5

Policy5

Provider6

Provider Specification5

Query1

Release4

Report versions8

Reports6

Role and grant5

Runtime Configuration5

Scope10

Scope type5

Service15

Suggestion8

Technology template5

User4

Workflow aliases7

Workflow definitions7

Workflow engine1

Workflow executions10

Workflow plugins2

Workflow revisions2

Workflow secrets and variables5

Workflow signals3

Workflow triggers1

Scope

Create a scope

Changed on Oct 15, 2026

Create a new scope in an existing application.

post/scope

Request

Base URL
https://api.nullplatform.com
URL
https://api.nullplatform.com/scope
Auth
HTTP bearer

Request body

namestring required

The name of the scope.

type'custom' | 'web_pool' | 'web_pool_k8s' | 'serverless' required

Defines the kind of scope to create.

ℹ️ Note:

• 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.

• Legacy scopes: The other types are older, predefined scope types that depend on fixed infrastructure configurations.

Identifies the provider that powers this scope.

ℹ️ Note:

• 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.

• Legacy scopes: One of the predefined provider strings (for example, "AWS:WEB_POOL:EKS" or "GOOGLE:WEB_POOL:GKE").

application_idinteger required

The ID of the application that owns this scope.

capabilitiesobject

Optional features such as logging, auto scaling, and spot instances. See the capabilities docs.

messagesobject

Additional system messages related to the scope's status or configuration.

external_createdboolean

Indicates whether the scope was provisioned externally. false when provisioned by nullplatform; true if created externally (e.g., via Terraform/OpenTofu).

tier'testing' | 'non_critical' | 'important' | 'critical'

Defines the tier type of the scope.

domainstring

A custom domain for the scope. Auto-generated if not provided.

asset_namestring

The name of the asset.

tagsstring[]

Tags to associate with the scope.

dimensionsobject

Defines runtime configuration dimensions, such as environment or region, that apply to this scope.

profilesstring[]

NRN profiles to apply to this scope, independent of runtime configurations.

instance_idstring

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.

Example request

{
  "name": "Billing API",
  "type": "custom",
  "provider": "9e84a5c3-6c2e-4f15-90b0-1c67fd37f6e8",
  "application_id": 2345,
  "requested_spec": {
    "memory_in_gb": 2,
    "cpu_profile": "standard",
    "local_storage_in_gb": 8
  },
  "tier": "important",
  "domain": "billing-api-prod.nullapps.io",
  "asset_name": "main-asset",
  "tags": [
    "requires_deployment",
    "high_priority"
  ],
  "dimensions": {
    "environment": "production"
  },
  "profiles": [
    "environment_production"
  ],
  "instance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

The scope was created successfully.

nrnstring

The NRN of the scope.

settingsobject nullable

Settings attached to the scope. null when none are set.

idinteger required

A system-wide unique ID for the scope. Assigned by nullplatform.

namestring required

The name of the scope.

asset_namestring

The name of the asset.

type'custom' | 'web_pool' | 'web_pool_k8s' | 'serverless' required

Defines the kind of scope you create.

ℹ️ Note:

• Agent-backed scopes: Use custom to create a scope managed by your installed agent.

• Legacy scopes: The other types are older, predefined scope types that depend on fixed infrastructure configurations.

Identifies the provider that powers this scope.

ℹ️ Note:

• 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.

• Legacy scopes: One of the predefined provider strings.

The status of the scope.

slugstring required

An application-wide unique slug for the scope. nullplatform derives it from the name when the scope is created: you can't send it, and it never changes afterwards.

domainstring required

An application-wide unique domain for the scope.

application_idinteger required

The ID of the application that owns this scope.

capabilitiesobject

Defines optional features such as logging, auto scaling, and spot instances. See the capabilities documentation for details.

messagesobject

Additional system messages related to the scope's status or configuration.

tier'testing' | 'non_critical' | 'important' | 'critical'

Defines the tier type of the scope.

external_createdboolean

Indicates whether the scope was provisioned externally. false when provisioned by nullplatform, true if created externally (e.g., via Terraform).

tagsstring[]

Tags associated with the scope.

profilesstring[]

NRN profiles that must be applied to this scope, independent of runtime configurations.

dimensionsobject

Defines runtime configuration dimensions, such as environment or region, that apply to this scope.

runtime_configurationsinteger[]

Runtime configurations that apply to this scope, resolved by nullplatform from its dimension values. Assign them by setting the scope's dimensions, not by sending this field.

instance_idstring

A unique identifier for the runtime instance associated with this scope.

application_namestring

The name of the application that owns this scope.

active_deploymentobject nullable

The last finalized deployment for this scope, or null if no deployment has been completed.

current_active_deploymentobject nullable

The currently running deployment for this scope.

in_progress_deploymentobject nullable

A new deployment currently in progress, or null if none.

stops_atstring date-time nullable

The ISO-8601 UTC timestamp when this scope is scheduled to stop, or null if not scheduled.

token_for_linksstring

A JWT token for generating authenticated scope links. Only present for organizations with generate_domain_token enabled.

created_atstring date-time

The ISO-8601 UTC timestamp of when the scope was created.

updated_atstring date-time

The ISO-8601 UTC timestamp of when the scope was last updated.

Example response

{
  "nrn": "organization=1:account=2:namespace=3:application=4:scope=5",
  "id": 1234,
  "name": "Billing API",
  "asset_name": "main-asset",
  "type": "custom",
  "provider": "9e84a5c3-6c2e-4f15-90b0-1c67fd37f6e8",
  "status": "active",
  "slug": "billing-api",
  "domain": "billing-api-prod.nullapps.io",
  "application_id": 2345,
  "requested_spec": {
    "memory_in_gb": 2,
    "cpu_profile": "standard",
    "local_storage_in_gb": 8
  },
  "tier": "important",
  "tags": [
    "requires_deployment",
    "high_priority"
  ],
  "profiles": [
    "environment_production"
  ],
  "dimensions": {
    "environment": "production"
  },
  "runtime_configurations": [
    1234,
    2345
  ],
  "domains": [
    {
      "id": "e78a0d21-3c48-7421-81cd-203fe84b8e47",
      "name": "api.crypto-inc.com",
      "type": "scope",
      "nrn": "organization=1:account=2:namespace=3:application=4:scope=1234",
      "selector": {
        "organization_id": 1,
        "nrn": "organization=1:account=2:namespace=3:application=4:scope=1234",
        "scope_id": 1234
      },
      "status": "active",
      "created_at": "2025-01-02T00:00:00Z",
      "updated_at": "2025-02-02T00:00:00Z"
    }
  ],
  "instance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "application_name": "Billing Service",
  "stops_at": "2026-04-01T00:00:00Z",
  "created_at": "2025-01-02T00:00:00Z",
  "updated_at": "2025-06-15T12:30:00Z",
  "metadata": {
    "key": "value"
  }
}

Changes

Oct 15, 2026728d4df70ca1 Revision changes
- breaking
  the request property / became required
- breaking
  the request property / became required
- breaking
  the request property / became required
- breaking
  the response property became optional for the status
- breaking
  the response property became optional for the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the success response with the status
- warning
  the / request property's max was set to 128.00
- warning
  the / request property's max was set to 128.00
- warning
  the / request property's min was set to 0.05
- info
  the request property default value 2 was removed
- info
  the request property default value 2 was removed
- info
  media type application/json was changed to a more specific media type application/problem+json for the response status
- info
  media type application/json was changed to a more specific media type application/problem+json for the response status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  response property message deprecated
- info
  response property message deprecated
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the success response with the status
Sep 22, 2026730fb95f21b8 Revision changes
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  the response required property became read-only for the status
- info
  the response required property became read-only for the status

Operation history