---
title: Welcome to the nullplatform API!
sidebar_label: Welcome to our API
sidebar_position: 1
doc_id: 8aa016d4-85b9-42ee-a525-9dc77cba4a03
description: >-
  Guide to nullplatform API with OpenAPI specs, authentication, and key entities
  overview.
keywords:
  - API
  - OpenAPI
  - authentication
  - access tokens
  - personal access tokens
  - documentation
---

import FeatureGrid from "@site/src/components/FeatureGrid";
import WorkflowCanvas from "@site/src/components/WorkflowCanvas";
import entityHierarchy from "@site/src/components/WorkflowCanvas/examples/entity-hierarchy";

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:

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

:::info Machine users
Scripts, automations, and integrations authenticate with an **API key** and obtain access tokens from it. See the [API keys](/docs/authorization/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:

- <a target="_blank" href="/openapi.yaml" download="nullplatform-openapi.yaml">Nullplatform OpenAPI (YAML)</a>
- <a target="_blank" href="/openapi.json" download="nullplatform-openapi.json">Nullplatform OpenAPI (JSON)</a>

## 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:

<WorkflowCanvas
  workflow={entityHierarchy}
  height={380}
  exploreLabel="Click to explore the entity hierarchy"
/>

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

<FeatureGrid
  accent="green"
  items={[
    {
      title: "Applications",
      href: "/docs/application-api-index",
      icon: "box",
      description: "Create and manage applications, their repositories, and their settings.",
    },
    {
      title: "Deployments",
      href: "/docs/deployments-api-index",
      icon: "rocket",
      description: "Create deployments, manage deployment groups, and control rollout strategies.",
    },
    {
      title: "Scopes",
      href: "/docs/scopes-api-index",
      icon: "layers",
      description: "Manage the runtime environments your applications deploy to, including scope types and dimensions.",
    },
    {
      title: "Parameters",
      href: "/docs/parameters-api-index",
      icon: "sliders",
      description: "Manage configuration and secrets: parameters, their values, and their versions.",
    },
    {
      title: "Authorization",
      href: "/docs/authorization-api-index",
      icon: "shield",
      description: "Manage API keys, roles, and grants to control who can do what, and where.",
    },
    {
      title: "Notifications",
      href: "/docs/notification-api-index",
      icon: "bell",
      description: "Create 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:

    ```json
    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.

:::warning 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.

:::tip 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](/docs/authz-api-index).