Welcome to the nullplatform API!

Everything in nullplatform is an API. This guide gets you making calls in a couple of minutes and covers the conventions every endpoint follows. 🚀

Make your first call

All API requests need an access token in the Authorization header. To grab yours, log in to nullplatform, click your user menu (the avatar in the top-right corner), and select Copy personal access token. Then you're one request away:

curl -L "https://api.nullplatform.com/account" \
  -H "Authorization: Bearer $NP_ACCESS_TOKEN"

Machine users

Scripts, automations, and integrations authenticate with an API key and obtain access tokens from it. See the API keys docs for details.

OpenAPI specification

The nullplatform API is built on the OpenAPI 3.0 specification. Download the full spec to import into your API client or code generator:

Key entities

When working with the API, you'll interact with the following entities. Click each node to see what it is and how to query it:

Organization

Account

Namespace

Application

Scope

One organization per company. Accounts separate business units, namespaces group applications by team or domain (like "billing" or "fraud"), and each application deploys to one or more scopes (like "staging" or "EU").

Explore the API

ApplicationsCreate and manage applications, their repositories, and their settings.DeploymentsCreate deployments, manage deployment groups, and control rollout strategies.ScopesManage the runtime environments your applications deploy to, including scope types and dimensions.ParametersManage configuration and secrets: parameters, their values, and their versions.AuthorizationManage API keys, roles, and grants to control who can do what, and where.NotificationsCreate notification channels and route platform events to your integrations.

Or browse the full surface in the sidebar.

Listing entities, filtering, and sorting data

You can retrieve entity lists by making requests without specifying an ID (e.g., GET /account). Here are some key points:

Filtering: Use query parameters, e.g., GET /account?status=active. We support filtering by multiple values using a comma as a separator like GET /account?name=crypto-kong&status=active.
Sorting: Use the sort parameter with the field and order, e.g. GET /account?sort=name:desc. Available sorts are asc and desc.
Paging: Use limit and offset to navigate through paginated results. offset indicates where to start in the result set (default is 0), limit specifies the number of results per page (default is 30), and the response's total is the number of results that match your query. The maximum page size depends on the endpoint. For example, GET /application without a parent entity returns at most 100 results per page.
Specify the parent entity: You are authorized only to list things that you have access to, so you have to filter by the parent entity. For example, if you are searching for applications, specify under which namespace_id you'll be running the query (e.g., GET /application?namespace_id=123). You can specify multiple parent entities for the search (up to 10), as long as you have listing permissions for each of them.

Responses: All entities share a uniform response format for list requests:

GET /application?namespace_id=123
{
  "paging": {
    "total": 30,
    "offset": 0,
    "limit": 30
  },
  "results": [
    {
      "id": 1234,
      "name": "Billing API",
      "slug": "billing-api",
      "namespace_id": 123,
      "nrn": "organization=1:account=12:namespace=123:application=1234",
      "status": "active",
      "repository_url": "https://example.com/crypto-inc/accounting-billing-api",
      "repository_app_path": null,
      "is_mono_repo": false,
      "auto_deploy_on_creation": false,
      "template_id": 3456,
      "tags": {},
      "settings": {},
      "messages": [],
      "created_at": "2026-08-14T13:05:21.118Z",
      "updated_at": "2026-08-14T13:05:29.402Z"
    }
  ]
}

Reading a single entity returns the same fields plus metadata, the values attached through the metadata catalog. List responses don't include it.

Technical conventions

Use the right domain

Note that our API is hosted at https://api.nullplatform.com. We do not use the .io domain for the API.

PUT vs. PATCH

Use PATCH to update entities. It's the method our APIs expect, it only touches the fields you send, and on several endpoints it's the only one accepted. Applications, for example, answer any PUT with a 405 Method Not Allowed:

PUT /application/1234
{
  "message": "Applications allow only partial update through PATCH."
}

Reach for PUT only when the endpoint supports it and you deliberately want to replace a whole resource.

PUT replaces, it doesn't merge

Using PUT on the NRN API fully replaces the NRN content, so every field you leave out of the body is lost. Unless you're really sure of what you're doing, send a PATCH.

Permissions and access control

Nullplatform has a permission system that allows for granular access control:

API endpoints represent actions. Each endpoint corresponds to an action (e.g., deploy:create), and to call it you must have permission for that action. Some endpoints require permissions for additional actions.
Roles bundle actions. Every user has one or more roles (e.g., developer, admin) that determine which actions they can perform.
Roles are granted on specific resources. Being a developer in a test application doesn't automatically grant the same permissions in another application. The same role might be granted in one area of the organization but not in another, so it needs to be explicitly granted for each resource where access is required.
Permissions extend to child resources. If you have the developer role at the account level, you inherit permissions for all namespaces, applications, and scopes within that account.

Putting it all together

Action: Defines what you can do in nullplatform (e.g., deploy:create).
Role: Links a group of users (e.g., developer) to the actions required for that role (e.g., organization:read).
Resources: The specific part of the organization's assets that a user is granted access to (e.g., "application 8" or "application 4").

To grant a role on a resource, see the role and grant APIs.

Make your first call​

OpenAPI specification​

Key entities​

Explore the API​

Listing entities, filtering, and sorting data​

Technical conventions​

Use the right domain​

PUT vs. PATCH​

Permissions and access control​