Skip to main content

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
Account
Namespace
Application
Scope
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 50 and cannot exceed 200), and the response's total is the number of results that match your query.

  • 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": 200
      },
      "results": [
        {
          "id": 1234,
          "name": "Billing API",
          "slug": "billing-api",
          "namespace_id": 123,
          "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,
          "metadata": {}
        }
      ]
    }

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 specific fields.
  • Use PUT to replace the entire resource.
Be cautious when using PUT

Using PUT on NRN API fully replaces the NRN content. We recommend using PATCH unless you're really sure of what you're doing.

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.