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.
| Operation | Method and path | Who may call it |
|---|---|---|
| List applications | GET /api/orgs/{org}/applications | read |
| Create an application | POST /api/orgs/{org}/applications | admin |
| Get an application | GET /api/orgs/{org}/applications/{id} | read |
| Edit an application | PATCH /api/orgs/{org}/applications/{id} | write |
| Delete an application | DELETE /api/orgs/{org}/applications/{id} | admin |
| Regenerate the threat model | POST /api/orgs/{org}/applications/{id}/regenerate | write |
#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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
repoId | string | yes | The repository, by its id. |
name | string | yes | What the team calls the application. Up to 80 characters. |
path | string | no | Its 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No repository of this organisation has the repoId sent. |
| 409 | application_exists | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | What the team calls the application. Up to 80 characters. |
rules | string | no | Project rules: extra instructions for reviews and pentests. Up to 20,000 characters; an empty string clears them. |
threatModel | object | no | The parts of the threat model to replace. version, generatedAt and editedAt are set by Nullgap and cannot be sent. |
threatModel.summary | string | no | What the application is and does. Up to 10,000 characters. |
threatModel.notes | string | no | Free-form notes, always handed to reviews and pentests. Up to 20,000 characters. |
threatModel.assets | array of string | no | What the application protects. Up to 200 entries; empty ones are dropped. |
threatModel.actors | array of string | no | Who can reach it. Up to 200 entries. |
threatModel.trustBoundaries | array of string | no | Where trust changes. Up to 200 entries. |
threatModel.controls | array of string | no | What stands in an attacker's way. Up to 200 entries. |
threatModel.learned | array of string | no | Lessons from findings the team dismissed or accepted. Up to 200 entries. |
threatModel.entryPoints | array of object | no | Where input comes in. Up to 500 entries. |
threatModel.entryPoints[].name | string | yes | A short name for the entry point. Up to 200 characters. |
threatModel.entryPoints[].file | string | no | The file that handles it. Up to 400 characters. |
threatModel.entryPoints[].description | string | no | What 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No application of this organisation has that id. |
| 409 | application_exists | Another 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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)
| Field | Type | Always present | Description |
|---|---|---|---|
jobId | string | yes | The id of the queued job. |
{
"jobId": "job_b72c40e9a1d5"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The application id. |
orgId | string | yes | The organisation it belongs to. |
repoId | string | yes | The repository it lives in. |
name | string | yes | What the team calls it. |
path | string | yes | Its folder inside the repository. . is the whole repository. |
threatModel | ThreatModel | yes | |
rules | string | yes | Project rules: extra instructions for reviews and pentests, written by the team. May be empty. |
createdAt | string | yes | When it was created. |
updatedAt | string | yes | When it was last changed. |
#ThreatModel
What an application protects, who can reach it and what stands in the way. Reviews and pentests read it.
| Field | Type | Always present | Description |
|---|---|---|---|
version | integer | yes | Goes up by one every time the model is regenerated or edited. 0 means it has not been written yet. |
summary | string | yes | What the application is and does, in a paragraph. |
assets | array of string | yes | What the application protects. |
actors | array of string | yes | Who can reach it. |
entryPoints | array of object | yes | Where input comes in. |
entryPoints[].name | string | yes | A short name for the entry point. |
entryPoints[].file | string | no | The file that handles it, when known. |
entryPoints[].description | string | yes | What it does and who can call it. May be empty. |
trustBoundaries | array of string | yes | Where trust changes. |
controls | array of string | yes | What stands in an attacker's way. |
learned | array of string | yes | What Nullgap learned from findings the team dismissed or accepted. |
notes | string | yes | Free-form notes written by the team. Always handed to reviews and pentests. |
generatedAt | string or null | yes | When Nullgap last wrote the model from the code. Null if it never has. |
editedAt | string or null | yes | When a person last edited it. Null if nobody has. |
Nullgap documentation