Nullgap.dev Docs

API reference

Applications

The context Nullgap keeps for an application: its threat model and project rules.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
List applicationsGET /api/orgs/{org}/applicationsread
Create an applicationPOST /api/orgs/{org}/applicationsadmin
Get an applicationGET /api/orgs/{org}/applications/{id}read
Edit an applicationPATCH /api/orgs/{org}/applications/{id}write
Delete an applicationDELETE /api/orgs/{org}/applications/{id}admin
Regenerate the threat modelPOST /api/orgs/{org}/applications/{id}/regeneratewrite

#List applications

GET /api/orgs/{org}/applications

Returns every application of the organisation, each with its full threat model, as a plain list. The list is not paged.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/applications"

Answer (200, application/json)

The applications.

An array of Application.

[
  {
    "id": "app_2d8f1c63a9e4",
    "orgId": "org_5b1e7a90c3d2",
    "repoId": "repo_a41c09be77d3",
    "name": "Shop API",
    "path": "services/api",
    "threatModel": {
      "version": 3,
      "summary": "An online shop: a public storefront, a checkout that takes card payments through a payment provider, and a staff back office.",
      "assets": [
        "Customer addresses and order history"
      ],
      "actors": [
        "Anonymous visitor"
      ],
      "entryPoints": [
        {
          "name": "POST /api/checkout",
          "file": "services/api/src/checkout.ts",
          "description": "Places an order. Any signed-in customer."
        }
      ],
      "trustBoundaries": [
        "Browser to API"
      ],
      "controls": [
        "Every /admin route requires the staff role"
      ],
      "learned": [
        "Coupon codes are public by design; guessing one is not a finding."
      ],
      "notes": "The back office is only reachable from the office network.",
      "generatedAt": "2026-11-10T08:00:00.000Z",
      "editedAt": "2026-11-12T15:20:00.000Z"
    },
    "rules": "Treat every /internal route as reachable only from the office network.",
    "createdAt": "2026-11-16T09:30:00.000Z",
    "updatedAt": "2026-11-12T15:20:00.000Z"
  }
]

#Create an application

POST /api/orgs/{org}/applications

Names one application inside a repository, so that Nullgap keeps a threat model and project rules for it. It starts with an empty threat model (version 0) and no rules; regenerate it to have Nullgap write the model from the code, or write it yourself.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
repoIdstringyesThe repository, by its id.
namestringyesWhat the team calls the application. Up to 80 characters.
pathstringnoIts folder inside the repository, relative and without ... Up to 300 characters. Default ., the whole repository.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId":"repo_a41c09be77d3","name":"Shop API","path":"services/api"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/applications"

Answer (200, application/json)

A Application object.

{
  "id": "app_2d8f1c63a9e4",
  "orgId": "org_5b1e7a90c3d2",
  "repoId": "repo_a41c09be77d3",
  "name": "Shop API",
  "path": "services/api",
  "threatModel": {
    "version": 3,
    "summary": "An online shop: a public storefront, a checkout that takes card payments through a payment provider, and a staff back office.",
    "assets": [
      "Customer addresses and order history"
    ],
    "actors": [
      "Anonymous visitor"
    ],
    "entryPoints": [
      {
        "name": "POST /api/checkout",
        "file": "services/api/src/checkout.ts",
        "description": "Places an order. Any signed-in customer."
      }
    ],
    "trustBoundaries": [
      "Browser to API"
    ],
    "controls": [
      "Every /admin route requires the staff role"
    ],
    "learned": [
      "Coupon codes are public by design; guessing one is not a finding."
    ],
    "notes": "The back office is only reachable from the office network.",
    "generatedAt": "2026-11-10T08:00:00.000Z",
    "editedAt": "2026-11-12T15:20:00.000Z"
  },
  "rules": "Treat every /internal route as reachable only from the office network.",
  "createdAt": "2026-11-16T09:30:00.000Z",
  "updatedAt": "2026-11-12T15:20:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo repository of this organisation has the repoId sent.
409application_existsThe repository already has an application for the same folder, or one with the same name (case does not matter).

#Get an application

GET /api/orgs/{org}/applications/{id}

Returns one application with its threat model and rules.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/applications/ID"

Answer (200, application/json)

A Application object.

{
  "id": "app_2d8f1c63a9e4",
  "orgId": "org_5b1e7a90c3d2",
  "repoId": "repo_a41c09be77d3",
  "name": "Shop API",
  "path": "services/api",
  "threatModel": {
    "version": 3,
    "summary": "An online shop: a public storefront, a checkout that takes card payments through a payment provider, and a staff back office.",
    "assets": [
      "Customer addresses and order history"
    ],
    "actors": [
      "Anonymous visitor"
    ],
    "entryPoints": [
      {
        "name": "POST /api/checkout",
        "file": "services/api/src/checkout.ts",
        "description": "Places an order. Any signed-in customer."
      }
    ],
    "trustBoundaries": [
      "Browser to API"
    ],
    "controls": [
      "Every /admin route requires the staff role"
    ],
    "learned": [
      "Coupon codes are public by design; guessing one is not a finding."
    ],
    "notes": "The back office is only reachable from the office network.",
    "generatedAt": "2026-11-10T08:00:00.000Z",
    "editedAt": "2026-11-12T15:20:00.000Z"
  },
  "rules": "Treat every /internal route as reachable only from the office network.",
  "createdAt": "2026-11-16T09:30:00.000Z",
  "updatedAt": "2026-11-12T15:20:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo application of this organisation has that id.

#Edit an application

PATCH /api/orgs/{org}/applications/{id}

Changes an application's name, its project rules, or parts of its threat model. Fields left out keep their value; inside threatModel, each list that is sent replaces the stored list as a whole. Sending threatModel at all, even empty, raises its version by one and sets editedAt. The repository and path cannot be changed. Any member of the organisation may edit.

Who may call it: An API key with the write scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
namestringnoWhat the team calls the application. Up to 80 characters.
rulesstringnoProject rules: extra instructions for reviews and pentests. Up to 20,000 characters; an empty string clears them.
threatModelobjectnoThe parts of the threat model to replace. version, generatedAt and editedAt are set by Nullgap and cannot be sent.
threatModel.summarystringnoWhat the application is and does. Up to 10,000 characters.
threatModel.notesstringnoFree-form notes, always handed to reviews and pentests. Up to 20,000 characters.
threatModel.assetsarray of stringnoWhat the application protects. Up to 200 entries; empty ones are dropped.
threatModel.actorsarray of stringnoWho can reach it. Up to 200 entries.
threatModel.trustBoundariesarray of stringnoWhere trust changes. Up to 200 entries.
threatModel.controlsarray of stringnoWhat stands in an attacker's way. Up to 200 entries.
threatModel.learnedarray of stringnoLessons from findings the team dismissed or accepted. Up to 200 entries.
threatModel.entryPointsarray of objectnoWhere input comes in. Up to 500 entries.
threatModel.entryPoints[].namestringyesA short name for the entry point. Up to 200 characters.
threatModel.entryPoints[].filestringnoThe file that handles it. Up to 400 characters.
threatModel.entryPoints[].descriptionstringnoWhat it does and who can call it. Up to 1000 characters.

Example request

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Shop API","rules":"Treat every /internal route as reachable only from the office network.","threatModel":{"summary":"An online shop with a public storefront, a checkout and a staff back office.","notes":"The back office is only reachable from the office network.","assets":["Customer addresses and order history"],"actors":["Anonymous visitor"],"trustBoundaries":["Browser to API"],"controls":["Every /admin route requires the staff role"],"learned":["Coupon codes are public by design; guessing one is not a finding."],"entryPoints":[{"name":"POST /api/checkout","file":"services/api/src/checkout.ts","description":"Places an order. Any signed-in customer."}]}}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/applications/ID"

Answer (200, application/json)

A Application object.

{
  "id": "app_2d8f1c63a9e4",
  "orgId": "org_5b1e7a90c3d2",
  "repoId": "repo_a41c09be77d3",
  "name": "Shop API",
  "path": "services/api",
  "threatModel": {
    "version": 3,
    "summary": "An online shop: a public storefront, a checkout that takes card payments through a payment provider, and a staff back office.",
    "assets": [
      "Customer addresses and order history"
    ],
    "actors": [
      "Anonymous visitor"
    ],
    "entryPoints": [
      {
        "name": "POST /api/checkout",
        "file": "services/api/src/checkout.ts",
        "description": "Places an order. Any signed-in customer."
      }
    ],
    "trustBoundaries": [
      "Browser to API"
    ],
    "controls": [
      "Every /admin route requires the staff role"
    ],
    "learned": [
      "Coupon codes are public by design; guessing one is not a finding."
    ],
    "notes": "The back office is only reachable from the office network.",
    "generatedAt": "2026-11-10T08:00:00.000Z",
    "editedAt": "2026-11-12T15:20:00.000Z"
  },
  "rules": "Treat every /internal route as reachable only from the office network.",
  "createdAt": "2026-11-16T09:30:00.000Z",
  "updatedAt": "2026-11-12T15:20:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo application of this organisation has that id.
409application_existsAnother application in the same repository already has that name.

#Delete an application

DELETE /api/orgs/{org}/applications/{id}

Removes an application with its threat model and rules. The repository, its findings and its past runs are not touched.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/applications/ID"

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundNo application of this organisation has that id.

#Regenerate the threat model

POST /api/orgs/{org}/applications/{id}/regenerate

Queues a job in which Nullgap AI reads the application's code and writes its threat model again. The call returns at once with the job's id; read the application later and look at threatModel.version and generatedAt to see that it has finished. Takes no body.

Who may call it: An API key with the write scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/applications/ID/regenerate"

Answer (200, application/json)

FieldTypeAlways presentDescription
jobIdstringyesThe id of the queued job.
{
  "jobId": "job_b72c40e9a1d5"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo application of this organisation has that id.

#Objects

The objects the operations above take and return.

#Application

One application inside a repository, with the context Nullgap keeps about it.

FieldTypeAlways presentDescription
idstringyesThe application id.
orgIdstringyesThe organisation it belongs to.
repoIdstringyesThe repository it lives in.
namestringyesWhat the team calls it.
pathstringyesIts folder inside the repository. . is the whole repository.
threatModelThreatModelyes
rulesstringyesProject rules: extra instructions for reviews and pentests, written by the team. May be empty.
createdAtstringyesWhen it was created.
updatedAtstringyesWhen it was last changed.

#ThreatModel

What an application protects, who can reach it and what stands in the way. Reviews and pentests read it.

FieldTypeAlways presentDescription
versionintegeryesGoes up by one every time the model is regenerated or edited. 0 means it has not been written yet.
summarystringyesWhat the application is and does, in a paragraph.
assetsarray of stringyesWhat the application protects.
actorsarray of stringyesWho can reach it.
entryPointsarray of objectyesWhere input comes in.
entryPoints[].namestringyesA short name for the entry point.
entryPoints[].filestringnoThe file that handles it, when known.
entryPoints[].descriptionstringyesWhat it does and who can call it. May be empty.
trustBoundariesarray of stringyesWhere trust changes.
controlsarray of stringyesWhat stands in an attacker's way.
learnedarray of stringyesWhat Nullgap learned from findings the team dismissed or accepted.
notesstringyesFree-form notes written by the team. Always handed to reviews and pentests.
generatedAtstring or nullyesWhen Nullgap last wrote the model from the code. Null if it never has.
editedAtstring or nullyesWhen a person last edited it. Null if nobody has.

Nullgap documentation