Data models #

This page documents the main public payloads exchanged with the Kuzzle PaaS API.

Organization #

{
  "id": "paas-org-my-company",
  "name": "My Company",
  "slug": "my_company",
  "description": "Acme Inc."
}

Fields:

id: organization tenant index. It is omitted when creating an organization.
name: organization display name (free, non-unique).
slug: organization slug used as the tenant name (generated from the display name).
description: optional organization description.

Project #

A project is a multi-tenancy soft tenant of its organization. It is identified by a short projectId and its external resources are addressed by a resource key derived from the organization slug and the project id.

{
  "name": "my-project",
  "description": "Customer production project",
  "resourceKey": "my-company-my-project"
}

Membership #

Returned by organization:listMembers.

{
  "userId": "kuid-john-doe",
  "roles": ["member"],
  "softTenants": ["my-project"]
}

Fields:

userId: the member's Kuzzle user id.
roles: organization roles, among owner, admin, member, external.
softTenants: the project ids the member is attached to.

Environment #

{
  "name": "production",
  "description": "Production environment",
  "projectId": "my-project",
  "applications": [],
  "size": "M",
  "status": "Deployed",
  "tier": "prod",
  "release": {
    "branch": "main",
    "protection": {
      "status": "protected",
      "checkedAt": "2026-09-30T10:00:00.000Z",
      "ruleset": "paas-console:release-branch:main"
    }
  },
  "keycloak": {
    "enabled": true,
    "realmName": "my-company-my-project-production"
  }
}

Fields:

name: environment identifier.
description: human-readable description.
projectId: parent project identifier.
applications: applications deployed in this environment.
size: one of S, S_SLA, M, L.
status: one of Deploying, Deployed, Upgrading, Disabled, Errored.
tier: optional deployment tier, one of uat, staging, prod.
release: optional release mapping. branch is the release branch of the environment; protection is the outcome of the last tier-driven protection of that branch (status: protected, unprotected or failed, with ruleset or error).
keycloak: optional Keycloak realm metadata.

Application #

{
  "_id": "api",
  "name": "kuzzleES8",
  "metadata": {
    "finalizers": ["resources-finalizer.argocd.argoproj.io"],
    "namespace": "delivery",
    "name": "api-production-my-company-my-project"
  },
  "spec": {
    "destination": {
      "namespace": "my-company-my-project",
      "server": "https://kubernetes.default.svc"
    },
    "source": {
      "chart": "paas-kuzzle-es8",
      "repoURL": "https://kuzzleio.github.io/helm-charts/",
      "targetRevision": "1.5.0",
      "helm": {
        "releaseName": "api-production-my-company-my-project",
        "values": {}
      }
    },
    "syncPolicy": {
      "automated": {
        "allowEmpty": true,
        "prune": true
      }
    },
    "project": "my-company-my-project"
  },
  "settings": {
    "projectId": "my-project",
    "environmentId": "production",
    "customDomain": "api.example.com",
    "customPort": 7512,
    "linkedWebAppId": "webapp",
    "protocols": [
      {
        "name": "http",
        "port": 7512
      }
    ]
  },
  "status": "Healthy"
}

Fields:

_id: application identifier inside the environment.
name: application type. Public values are kuzzle, kuzzleES8, webapp, custom.
metadata: ArgoCD application metadata.
spec: ArgoCD application specification.
settings: Kuzzle PaaS application settings.
status: application health status (Healthy, Progressing, Degraded, Suspended).

Application settings #

{
  "projectId": "my-project",
  "environmentId": "production",
  "customDomain": "api.example.com",
  "customCertificates": ["tls-secret-name"],
  "customPort": 7512,
  "linkedWebAppId": "webapp",
  "keycloak": {
    "clientId": "api",
    "secret": "<client-secret>",
    "realm": "my-company-my-project-production"
  },
  "protocols": [
    {
      "name": "http",
      "port": 7512
    }
  ]
}

Release #

Returned by the org-release controller.

{
  "_id": "<release-id>",
  "projectId": "my-project",
  "version": "v1.4.0",
  "gitRef": { "branch": "main", "sha": "<commit-sha>" },
  "channel": "latest",
  "releaseRun": {
    "runId": 123456789,
    "htmlUrl": "https://github.com/<owner>/<repo>/actions/runs/123456789",
    "status": "completed",
    "conclusion": "success",
    "dispatchId": "<dispatch-id>"
  },
  "outcome": "released",
  "changelog": "<release notes>",
  "createdBy": "kuid-john-doe",
  "createdAt": "2026-09-30T10:00:00.000Z"
}

Fields:

version: the tag of the GitHub Release produced by the run; null until the run has succeeded.
gitRef: the release branch and the commit the run released.
channel: latest for a stable version, otherwise its prerelease identifier (beta, dev...).
releaseRun: the release.yml workflow run. status is dispatched until the run is found, then the GitHub run status (queued, in_progress, completed).
outcome: absent while the release is in flight, then released, no-release or failed.

Deployment #

Returned by the org-deployment controller.

{
  "_id": "<deployment-id>",
  "projectId": "my-project",
  "environmentId": "production",
  "releaseId": "<release-id>",
  "buildRun": {
    "runId": 123456790,
    "htmlUrl": "https://github.com/<owner>/<repo>/actions/runs/123456790",
    "status": "completed",
    "dispatchId": "<dispatch-id>"
  },
  "images": [
    { "app": "api", "name": "harbor.paas.kuzzle.io/my-company-my-project/production/api", "tag": "v1.4.0" }
  ],
  "previousImages": [
    { "app": "api", "name": "harbor.paas.kuzzle.io/my-company-my-project/production/api", "tag": "v1.3.2" }
  ],
  "argo": { "sync": "Synced", "health": "Healthy" },
  "status": "succeeded",
  "triggeredBy": "kuid-john-doe",
  "triggeredAt": "2026-09-30T10:05:00.000Z",
  "deployingAt": "2026-09-30T10:09:00.000Z"
}

Fields:

buildRun: the build.yml workflow run.
images / previousImages: per application (app = application _id), the image applied and the one it replaced — the latter is what rollback re-applies.
argo: last observed ArgoCD sync and health of the environment.
status: pending, building, deploying, succeeded, failed or rolled-back (see Statuses).
failure: on a failed deployment only — phase (build, apply or deploy), message, and for the deploy phase the unhealthy resources (kind, name, status, message).
deployingAt: when the images were applied.

The image repository of an application is <registry>/<harbor project>/<environment>/<application _id>, the tag is the release version.

Image #

Used by org-application:deploy.

{
  "name": "harbor.paas.kuzzle.io/my-company-my-project/api",
  "tag": "1.2.3"
}

Kuzzle document wrapper #

Some configuration endpoints return Kuzzle documents:

{
  "_id": "slack",
  "_source": {
    "webhookUrl": "https://hooks.slack.com/services/..."
  },
  "_kuzzle_info": {
    "author": "-1",
    "createdAt": 1781870400000,
    "updatedAt": 1781870400000,
    "updater": "-1"
  }
}