Nullgap.dev Docs

API reference

Skills

The catalogue of skills, its switches and per-repository overrides, and the skills you write yourself.

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 skillsGET /api/orgs/{org}/skillsread
Add a custom skillPOST /api/orgs/{org}/skillsadmin
Check a skill without saving itPOST /api/orgs/{org}/skills/validatewrite
Upload a skill folderPOST /api/orgs/{org}/skills/importadmin
Set permitted tools, repository overrides and the pentest switchPUT /api/orgs/{org}/skills/settingsadmin
Get a skillGET /api/orgs/{org}/skills/{id}read
Replace a custom skillPUT /api/orgs/{org}/skills/{id}admin
Remove a custom skillDELETE /api/orgs/{org}/skills/{id}admin
Switch a skill onPOST /api/orgs/{org}/skills/{id}/enableadmin
Switch a skill offPOST /api/orgs/{org}/skills/{id}/disableadmin

#List skills

GET /api/orgs/{org}/skills

Returns every skill the organisation can use, built in and its own, each with whether it is switched on and whether the tools it names can be used here. The same answer carries the tool list, the organisation's switches and per-repository overrides, the categories and the limits, so one call is enough to show the whole page. The answer is an object, not a page.

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/skills"

Answer (200, application/json)

A SkillCatalogue object.

{
  "skills": [
    {
      "manifest": {
        "id": "injection-review",
        "title": "Injection review",
        "version": "1.2.0",
        "category": "appsec",
        "description": "Traces request data into SQL, shell and template sinks and reports the paths that reach one unchecked.",
        "license": "Apache-2.0",
        "compatibility": "Needs the code index.",
        "author": "Acme platform security",
        "appliesTo": {
          "scope": "file",
          "pipelines": [
            "review"
          ],
          "filePatterns": [
            "src/**/*.ts"
          ],
          "languages": [
            "typescript"
          ],
          "technologies": [
            "express"
          ]
        },
        "tools": [
          "static-rules"
        ],
        "inputs": [
          {
            "name": "repository",
            "required": true
          }
        ],
        "output": {
          "kind": "findings",
          "document": "threat-model"
        },
        "limits": {
          "tokenShare": 0.05,
          "timeMinutes": 10,
          "maxSteps": 12
        }
      },
      "origin": "built-in",
      "enabled": true,
      "tools": [
        {
          "id": "static-rules",
          "available": true,
          "permitted": true
        }
      ],
      "custom": {
        "createdBy": "dana@acme.example",
        "updatedAt": "2026-11-16T09:30:00.000Z",
        "imported": false,
        "otherFiles": [
          {
            "path": "scripts/check.sh",
            "bytes": 2048
          }
        ],
        "note": "A custom skill guides where the review looks. Its scripts are never run on Nullgap servers."
      }
    }
  ],
  "tools": [
    {
      "id": "static-rules",
      "title": "Built-in static rules",
      "description": "Pattern rules for common weaknesses across languages. Leads on file and line.",
      "kind": "built-in",
      "network": "none",
      "output": "leads",
      "available": true,
      "unavailableReason": "not installed on this server",
      "permitted": true
    }
  ],
  "settings": {
    "disabled": [
      "injection-review"
    ],
    "repositories": {
      "repo_a41c09be77d3": {
        "enabled": [],
        "disabled": [
          "iac-review"
        ]
      }
    },
    "allowedTools": [
      "static-rules"
    ],
    "builtinInPentests": false
  },
  "categories": [
    {
      "id": "appsec",
      "title": "Application security"
    }
  ],
  "limits": {
    "customSkills": 40,
    "importBytes": 2097152,
    "importFiles": 200,
    "artifactBytes": 209715200,
    "artifacts": 20,
    "textChars": 200000,
    "skillMdChars": 48000
  },
  "about": "A custom check is a short brief that adds one thing to look for in every review and pentest. A skill is a whole packaged capability."
}

#Add a custom skill

POST /api/orgs/{org}/skills

Saves a skill written for the organisation. Its id is the name in the frontmatter. From then on it is chosen for reviews and pentests whenever it applies, next to the built-in skills, and can be run on demand if it says so. Whatever the text says, three things hold for a custom skill: its allowed-tools field is display only (the tools it may use are the ones the organisation permits), its instructions are handed over as data inside the run's own rules, and it cannot change the result format, the rules of evidence, the proof standard or the live-testing scope.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
skillMdstringyesThe whole text of a SKILL.md in the Agent Skills format: YAML frontmatter with name and description (and optionally license, compatibility, metadata, allowed-tools), then the instructions. Up to 48,000 characters.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skillMd":"---\nname: tenant-isolation\ndescription: Checks that every database lookup in a request handler is scoped to the tenant of the signed-in session. Use when reviewing data access code of a service that holds several tenants.\nmetadata:\n  author: acme\n  version: \"1.0\"\n  nullgap.pipelines: review pentest on-demand\n  nullgap.output: findings\n---\n\n## What to look for\nLookups by id that are not scoped to the tenant.\n\n## How to confirm\nRead the handler and the query it builds.\n\n## What is not a finding\nA lookup scoped by the tenant of the session.\n\n## How to report\nFile, line, entry point, path and sink.\n"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills"

Answer (200, application/json)

A SkillDetail object.

{
  "manifest": {
    "id": "injection-review",
    "title": "Injection review",
    "version": "1.2.0",
    "category": "appsec",
    "description": "Traces request data into SQL, shell and template sinks and reports the paths that reach one unchecked.",
    "license": "Apache-2.0",
    "compatibility": "Needs the code index.",
    "author": "Acme platform security",
    "appliesTo": {
      "scope": "file",
      "pipelines": [
        "review"
      ],
      "filePatterns": [
        "src/**/*.ts"
      ],
      "languages": [
        "typescript"
      ],
      "technologies": [
        "express"
      ]
    },
    "tools": [
      "static-rules"
    ],
    "inputs": [
      {
        "name": "repository",
        "required": true
      }
    ],
    "output": {
      "kind": "findings",
      "document": "threat-model"
    },
    "limits": {
      "tokenShare": 0.05,
      "timeMinutes": 10,
      "maxSteps": 12
    }
  },
  "origin": "built-in",
  "enabled": true,
  "tools": [
    {
      "id": "static-rules",
      "available": true,
      "permitted": true
    }
  ],
  "custom": {
    "createdBy": "dana@acme.example",
    "updatedAt": "2026-11-16T09:30:00.000Z",
    "imported": false,
    "otherFiles": [
      {
        "path": "scripts/check.sh",
        "bytes": 2048
      }
    ],
    "note": "A custom skill guides where the review looks. Its scripts are never run on Nullgap servers."
  },
  "skillMd": "---\nname: tenant-isolation\ndescription: Checks that every query is filtered by the tenant of the session.\n---\n\n## When to use\n..."
}

Errors specific to this call

StatusCodeWhen
400invalid_skillThe text is not an acceptable skill. The message lists every problem: a missing or malformed field, a name that is taken by a built-in skill or is one of validate, import and settings, instructions that are too short, a limit above what is allowed.
409duplicate_nameThe organisation already has a custom skill with that name. Change it with PUT, or choose another name.
409limit_reachedThe organisation already keeps 40 custom skills. Remove one first.

#Check a skill without saving it

POST /api/orgs/{org}/skills/validate

Reads a SKILL.md exactly as saving it would and answers with what is wrong, what will not work as written, and the settings that were read from it. Nothing is stored. A text that is refused still answers 200, with ok: false and the reasons in errors. A read-only key cannot call this, although it changes nothing.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
skillMdstringyesThe whole text of a SKILL.md in the Agent Skills format: YAML frontmatter with name and description (and optionally license, compatibility, metadata, allowed-tools), then the instructions. Up to 48,000 characters.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skillMd":"---\nname: tenant-isolation\ndescription: Checks that every database lookup in a request handler is scoped to the tenant of the signed-in session. Use when reviewing data access code of a service that holds several tenants.\nmetadata:\n  author: acme\n  version: \"1.0\"\n  nullgap.pipelines: review pentest on-demand\n  nullgap.output: findings\n---\n\n## What to look for\nLookups by id that are not scoped to the tenant.\n\n## How to confirm\nRead the handler and the query it builds.\n\n## What is not a finding\nA lookup scoped by the tenant of the session.\n\n## How to report\nFile, line, entry point, path and sink.\n"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills/validate"

Answer (200, application/json)

A SkillValidation object.

{
  "ok": true,
  "errors": [
    "description: required, one or two sentences on what the skill does and when to use it"
  ],
  "warnings": [
    "allowed-tools is shown but not used: the tools a skill may call are the ones your organisation permits"
  ],
  "manifest": {
    "id": "injection-review",
    "title": "Injection review",
    "version": "1.2.0",
    "category": "appsec",
    "description": "Traces request data into SQL, shell and template sinks and reports the paths that reach one unchecked.",
    "license": "Apache-2.0",
    "compatibility": "Needs the code index.",
    "author": "Acme platform security",
    "appliesTo": {
      "scope": "file",
      "pipelines": [
        "review"
      ],
      "filePatterns": [
        "src/**/*.ts"
      ],
      "languages": [
        "typescript"
      ],
      "technologies": [
        "express"
      ]
    },
    "tools": [
      "static-rules"
    ],
    "inputs": [
      {
        "name": "repository",
        "required": true
      }
    ],
    "output": {
      "kind": "findings",
      "document": "threat-model"
    },
    "limits": {
      "tokenShare": 0.05,
      "timeMinutes": 10,
      "maxSteps": 12
    }
  }
}

#Upload a skill folder

POST /api/orgs/{org}/skills/import

Adds a custom skill from a skill folder packed as a .zip or .tar.gz, up to 2 MB and 200 files. The request body is the archive itself, not JSON. SKILL.md must be at the top of the archive or inside its one folder. Only SKILL.md is kept. Every other file in the folder (scripts above all) is listed by name and size in custom.otherFiles and then deleted: nothing in them is read as instructions or run.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/octet-stream)

The bytes of the .zip or .tar.gz file.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @code.zip \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills/import"

Answer (200, application/json)

A SkillDetail object.

{
  "manifest": {
    "id": "injection-review",
    "title": "Injection review",
    "version": "1.2.0",
    "category": "appsec",
    "description": "Traces request data into SQL, shell and template sinks and reports the paths that reach one unchecked.",
    "license": "Apache-2.0",
    "compatibility": "Needs the code index.",
    "author": "Acme platform security",
    "appliesTo": {
      "scope": "file",
      "pipelines": [
        "review"
      ],
      "filePatterns": [
        "src/**/*.ts"
      ],
      "languages": [
        "typescript"
      ],
      "technologies": [
        "express"
      ]
    },
    "tools": [
      "static-rules"
    ],
    "inputs": [
      {
        "name": "repository",
        "required": true
      }
    ],
    "output": {
      "kind": "findings",
      "document": "threat-model"
    },
    "limits": {
      "tokenShare": 0.05,
      "timeMinutes": 10,
      "maxSteps": 12
    }
  },
  "origin": "built-in",
  "enabled": true,
  "tools": [
    {
      "id": "static-rules",
      "available": true,
      "permitted": true
    }
  ],
  "custom": {
    "createdBy": "dana@acme.example",
    "updatedAt": "2026-11-16T09:30:00.000Z",
    "imported": false,
    "otherFiles": [
      {
        "path": "scripts/check.sh",
        "bytes": 2048
      }
    ],
    "note": "A custom skill guides where the review looks. Its scripts are never run on Nullgap servers."
  },
  "skillMd": "---\nname: tenant-isolation\ndescription: Checks that every query is filtered by the tenant of the session.\n---\n\n## When to use\n..."
}

Errors specific to this call

StatusCodeWhen
400invalid_skillThe text is not an acceptable skill. The message lists every problem: a missing or malformed field, a name that is taken by a built-in skill or is one of validate, import and settings, instructions that are too short, a limit above what is allowed.
400bad_archiveThe upload is damaged, is neither a zip nor a gzip-compressed tar, holds more than 200 files, or unpacks to more than it may.
400bad_requestThe upload is empty.
409duplicate_nameThe organisation already has a custom skill with that name.
409limit_reachedThe organisation already keeps 40 custom skills. Remove one first.
413too_largeThe archive is larger than 2 MB.

#Set permitted tools, repository overrides and the pentest switch

PUT /api/orgs/{org}/skills/settings

Changes which tools skills may use, the per-repository overrides and whether built-in skills run in pentests, in one go. Turning builtinInPentests on or off is recorded in the audit log on its own. A field left out keeps its value; repositories, when sent, replaces the whole map. The organisation-wide switches are not changed here: use the enable and disable calls. In an override, skill ids the organisation does not have are dropped silently, an id in both lists counts as enabled, and the triage skill cannot be disabled. Answers with the settings as they now are.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
allowedToolsarray of string or nullnoThe tools skills may use. Null lifts the restriction: every tool this server has.
repositoriesobjectnoRepository id to the skills forced on and off there. Up to 500 repositories.
builtinInPentestsbooleannoRun the built-in skills as extra finders in pentests. Off unless an admin turns it on; custom skills run either way.

Example request

curl -s -X PUT -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowedTools":["static-rules"],"repositories":{"repo_a41c09be77d3":{"enabled":["iac-review"],"disabled":[]}},"builtinInPentests":false}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills/settings"

Answer (200, application/json)

A SkillSettings object.

{
  "disabled": [
    "injection-review"
  ],
  "repositories": {
    "repo_a41c09be77d3": {
      "enabled": [],
      "disabled": [
        "iac-review"
      ]
    }
  },
  "allowedTools": [
    "static-rules"
  ],
  "builtinInPentests": false
}

Errors specific to this call

StatusCodeWhen
400bad_requestallowedTools is neither null nor a list of known tool ids, repositories is not a map, one of its keys is not a repository of this organisation, or builtinInPentests is not true or false.

#Get a skill

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

Returns one skill with the full text of its SKILL.md. Works for built-in skills too, which is the easiest way to see how one is written.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe skill id: the name in its SKILL.md.

Example request

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

Answer (200, application/json)

A SkillDetail object.

{
  "manifest": {
    "id": "injection-review",
    "title": "Injection review",
    "version": "1.2.0",
    "category": "appsec",
    "description": "Traces request data into SQL, shell and template sinks and reports the paths that reach one unchecked.",
    "license": "Apache-2.0",
    "compatibility": "Needs the code index.",
    "author": "Acme platform security",
    "appliesTo": {
      "scope": "file",
      "pipelines": [
        "review"
      ],
      "filePatterns": [
        "src/**/*.ts"
      ],
      "languages": [
        "typescript"
      ],
      "technologies": [
        "express"
      ]
    },
    "tools": [
      "static-rules"
    ],
    "inputs": [
      {
        "name": "repository",
        "required": true
      }
    ],
    "output": {
      "kind": "findings",
      "document": "threat-model"
    },
    "limits": {
      "tokenShare": 0.05,
      "timeMinutes": 10,
      "maxSteps": 12
    }
  },
  "origin": "built-in",
  "enabled": true,
  "tools": [
    {
      "id": "static-rules",
      "available": true,
      "permitted": true
    }
  ],
  "custom": {
    "createdBy": "dana@acme.example",
    "updatedAt": "2026-11-16T09:30:00.000Z",
    "imported": false,
    "otherFiles": [
      {
        "path": "scripts/check.sh",
        "bytes": 2048
      }
    ],
    "note": "A custom skill guides where the review looks. Its scripts are never run on Nullgap servers."
  },
  "skillMd": "---\nname: tenant-isolation\ndescription: Checks that every query is filtered by the tenant of the session.\n---\n\n## When to use\n..."
}

Errors specific to this call

StatusCodeWhen
404not_foundThe organisation has no skill with that id, built in or its own.

#Replace a custom skill

PUT /api/orgs/{org}/skills/{id}

Replaces the text of a custom skill. The name in the new text must be the id in the path: a skill is renamed by adding it under the new name and removing the old one.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe skill id: the name in its SKILL.md.

Request body (application/json)

FieldTypeRequiredDescription
skillMdstringyesThe whole text of a SKILL.md in the Agent Skills format: YAML frontmatter with name and description (and optionally license, compatibility, metadata, allowed-tools), then the instructions. Up to 48,000 characters.

Example request

curl -s -X PUT -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skillMd":"---\nname: tenant-isolation\ndescription: Checks that every database lookup in a request handler is scoped to the tenant of the signed-in session. Use when reviewing data access code of a service that holds several tenants.\nmetadata:\n  author: acme\n  version: \"1.0\"\n  nullgap.pipelines: review pentest on-demand\n  nullgap.output: findings\n---\n\n## What to look for\nLookups by id that are not scoped to the tenant.\n\n## How to confirm\nRead the handler and the query it builds.\n\n## What is not a finding\nA lookup scoped by the tenant of the session.\n\n## How to report\nFile, line, entry point, path and sink.\n"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills/name"

Answer (200, application/json)

A SkillDetail object.

{
  "manifest": {
    "id": "injection-review",
    "title": "Injection review",
    "version": "1.2.0",
    "category": "appsec",
    "description": "Traces request data into SQL, shell and template sinks and reports the paths that reach one unchecked.",
    "license": "Apache-2.0",
    "compatibility": "Needs the code index.",
    "author": "Acme platform security",
    "appliesTo": {
      "scope": "file",
      "pipelines": [
        "review"
      ],
      "filePatterns": [
        "src/**/*.ts"
      ],
      "languages": [
        "typescript"
      ],
      "technologies": [
        "express"
      ]
    },
    "tools": [
      "static-rules"
    ],
    "inputs": [
      {
        "name": "repository",
        "required": true
      }
    ],
    "output": {
      "kind": "findings",
      "document": "threat-model"
    },
    "limits": {
      "tokenShare": 0.05,
      "timeMinutes": 10,
      "maxSteps": 12
    }
  },
  "origin": "built-in",
  "enabled": true,
  "tools": [
    {
      "id": "static-rules",
      "available": true,
      "permitted": true
    }
  ],
  "custom": {
    "createdBy": "dana@acme.example",
    "updatedAt": "2026-11-16T09:30:00.000Z",
    "imported": false,
    "otherFiles": [
      {
        "path": "scripts/check.sh",
        "bytes": 2048
      }
    ],
    "note": "A custom skill guides where the review looks. Its scripts are never run on Nullgap servers."
  },
  "skillMd": "---\nname: tenant-isolation\ndescription: Checks that every query is filtered by the tenant of the session.\n---\n\n## When to use\n..."
}

Errors specific to this call

StatusCodeWhen
400invalid_skillThe text is not an acceptable skill. The message lists every problem: a missing or malformed field, a name that is taken by a built-in skill or is one of validate, import and settings, instructions that are too short, a limit above what is allowed.
403forbiddenThe id is a built-in skill. A built-in skill cannot be edited: switch it off, or write a custom skill under another name.
404not_foundThe organisation has no custom skill with that id.

#Remove a custom skill

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

Removes a custom skill and every switch and override that names it. Findings and runs it already produced stay.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe skill id: the name in its SKILL.md.

Example request

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

Answer (200, application/json)

FieldTypeAlways presentDescription
okbooleanyesAlways true.
{
  "ok": true
}

Errors specific to this call

StatusCodeWhen
403forbiddenThe id is a built-in skill. A built-in skill cannot be removed: switch it off instead.
404not_foundThe organisation has no custom skill with that id.

#Switch a skill on

POST /api/orgs/{org}/skills/{id}/enable

Switches a skill on for the organisation, or for one repository when repoId is sent. A repository override is kept only where it differs from the organisation's own switch. Answers with the settings as they now are. The body may be left out.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe skill id: the name in its SKILL.md.

Request body (application/json)

FieldTypeRequiredDescription
repoIdstring or nullnoA repository id. Sent: the switch is set for that repository only, as an override of the organisation's own switch. Left out or null: it is set for the whole organisation.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId":"repo_a41c09be77d3"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills/name/enable"

Answer (200, application/json)

A SkillSettings object.

{
  "disabled": [
    "injection-review"
  ],
  "repositories": {
    "repo_a41c09be77d3": {
      "enabled": [],
      "disabled": [
        "iac-review"
      ]
    }
  },
  "allowedTools": [
    "static-rules"
  ],
  "builtinInPentests": false
}

Errors specific to this call

StatusCodeWhen
404not_foundThe organisation has no skill with that id, or no repository with the repoId sent.

#Switch a skill off

POST /api/orgs/{org}/skills/{id}/disable

Switches a skill off for the organisation, or for one repository when repoId is sent. A skill that is off is not chosen for reviews or pentests and cannot be run on demand. Answers with the settings as they now are. The body may be left out.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe skill id: the name in its SKILL.md.

Request body (application/json)

FieldTypeRequiredDescription
repoIdstring or nullnoA repository id. Sent: the switch is set for that repository only, as an override of the organisation's own switch. Left out or null: it is set for the whole organisation.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId":"repo_a41c09be77d3"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills/name/disable"

Answer (200, application/json)

A SkillSettings object.

{
  "disabled": [
    "injection-review"
  ],
  "repositories": {
    "repo_a41c09be77d3": {
      "enabled": [],
      "disabled": [
        "iac-review"
      ]
    }
  },
  "allowedTools": [
    "static-rules"
  ],
  "builtinInPentests": false
}

Errors specific to this call

StatusCodeWhen
404not_foundThe organisation has no skill with that id, or no repository with the repoId sent.
400always_onThe id is the triage skill. It is the playbook of the independent check every finding goes through, and cannot be switched off.

#Objects

The objects the operations above take and return.

#SkillCatalogue

The skills of an organisation with everything needed to show and manage them.

FieldTypeAlways presentDescription
skillsarray of SkillSummaryyesEvery skill the organisation can use: the built-in catalogue and its own, switched on or not.
toolsarray of SkillToolInfoyesEvery tool a skill can name, with whether it is installed and permitted here.
settingsSkillSettingsyes
categoriesarray of objectyesThe categories, in the order the console shows them.
categories[].idstringyesThe category id. One of: appsec, devsecops, secrets, secure-sdlc, compliance, incident-response.
categories[].titlestringyesIts display name.
limitsobjectyesThe limits skills are held to.
limits.customSkillsintegeryesCustom skills an organisation can keep.
limits.importBytesintegeryesLargest uploaded skill folder, in bytes.
limits.importFilesintegeryesMost files an uploaded skill folder may hold.
limits.artifactBytesintegeryesLargest file uploaded for a comparison, in bytes.
limits.artifactsintegeryesUploads for a comparison an organisation can keep at a time.
limits.textCharsintegeryesLongest text given to a run, in characters.
limits.skillMdCharsintegeryesLongest SKILL.md, in characters.
aboutstringyesHow a skill differs from a custom check, in a sentence to show to people.

#SkillDetail

One skill with its full text.

FieldTypeAlways presentDescription
manifestSkillManifestyes
originstringyesbuilt-in: part of the catalogue that ships with Nullgap. custom: written or uploaded by this organisation.
enabledbooleanyesWhether the skill is on for the organisation. A repository can still override this either way; see settings.repositories in the catalogue answer.
toolsarray of objectyesThe tools the skill names, each with whether it can be used here. A skill still runs when a tool is missing: it works from the code alone and says so.
tools[].idstringyesA tool id. One of: static-rules, code-index, dependency-audit, package-check, sandbox-run, live-request, browser-check, git-history, static-analysis, secret-detection, dependency-scan, container-scan, iac-check, dockerfile-check, kubernetes-check, ci-workflow-check, api-description-check, policy-check, sbom, decompile, web-scan.
tools[].availablebooleanyesWhether the tool can run on this server right now.
tools[].permittedbooleanyesWhether the organisation lets skills use it.
customobjectnoPresent on custom skills only.
custom.createdBystringyesWho first saved it: an e-mail address, or the name of an API key.
custom.updatedAtstringyesWhen it was last saved.
custom.importedbooleanyesTrue when it came from an uploaded skill folder rather than from text sent to the API or typed in the console.
custom.otherFilesarray of objectyesFiles the uploaded folder held besides SKILL.md. Only their names and sizes are kept: they were deleted on arrival and are never read or run.
custom.otherFiles[].pathstringyesThe file's path inside the uploaded folder.
custom.otherFiles[].bytesintegeryesIts size in bytes.
custom.notestring or nullyesWhat the hosted product does not do with a custom skill, in a sentence to show next to it.
skillMdstringyesThe whole SKILL.md, frontmatter included.

#SkillValidation

The result of checking a SKILL.md without saving it.

FieldTypeAlways presentDescription
okbooleanyesTrue when the text would be accepted as a custom skill.
errorsarray of stringyesWhy it would be refused. Empty when ok is true.
warningsarray of stringyesThings that do not stop it being saved but will not work as written. Empty when ok is false.
manifestSkillManifestnoThe settings read from the text, when ok is true.

#SkillSettings

The organisation's choices about skills.

FieldTypeAlways presentDescription
disabledarray of stringyesSkills switched off for the whole organisation. Every other skill is on.
repositoriesobjectyesPer repository id: skills forced on or off there, whatever the organisation's own switch says. A repository with no override is not listed.
allowedToolsarray of string or nullyesThe tools skills may use in this organisation. Null means every tool this server has.
builtinInPentestsbooleanyesWhether the built-in skills run as extra finders inside pentests. Off by default: they mostly repeat what the main analysis and the scanning tools already find, and each adds cost. The organisation's own custom skills and the triage playbook run either way, and pull request reviews are not affected.

#SkillSummary

A skill as the catalogue lists it.

FieldTypeAlways presentDescription
manifestSkillManifestyes
originstringyesbuilt-in: part of the catalogue that ships with Nullgap. custom: written or uploaded by this organisation.
enabledbooleanyesWhether the skill is on for the organisation. A repository can still override this either way; see settings.repositories in the catalogue answer.
toolsarray of objectyesThe tools the skill names, each with whether it can be used here. A skill still runs when a tool is missing: it works from the code alone and says so.
tools[].idstringyesA tool id. One of: static-rules, code-index, dependency-audit, package-check, sandbox-run, live-request, browser-check, git-history, static-analysis, secret-detection, dependency-scan, container-scan, iac-check, dockerfile-check, kubernetes-check, ci-workflow-check, api-description-check, policy-check, sbom, decompile, web-scan.
tools[].availablebooleanyesWhether the tool can run on this server right now.
tools[].permittedbooleanyesWhether the organisation lets skills use it.
customobjectnoPresent on custom skills only.
custom.createdBystringyesWho first saved it: an e-mail address, or the name of an API key.
custom.updatedAtstringyesWhen it was last saved.
custom.importedbooleanyesTrue when it came from an uploaded skill folder rather than from text sent to the API or typed in the console.
custom.otherFilesarray of objectyesFiles the uploaded folder held besides SKILL.md. Only their names and sizes are kept: they were deleted on arrival and are never read or run.
custom.otherFiles[].pathstringyesThe file's path inside the uploaded folder.
custom.otherFiles[].bytesintegeryesIts size in bytes.
custom.notestring or nullyesWhat the hosted product does not do with a custom skill, in a sentence to show next to it.

#SkillToolInfo

A tool a skill can call.

FieldTypeAlways presentDescription
idstringyesA tool id. One of: static-rules, code-index, dependency-audit, package-check, sandbox-run, live-request, browser-check, git-history, static-analysis, secret-detection, dependency-scan, container-scan, iac-check, dockerfile-check, kubernetes-check, ci-workflow-check, api-description-check, policy-check, sbom, decompile, web-scan.
titlestringyesThe display name.
descriptionstringyesWhat it does.
kindstringyesbuilt-in: part of Nullgap itself. external: a scanner the operator of the server installs.
networkstringyesnone: reads the checkout only. outbound: contacts a public database. target: sends requests to the application under test, which only ever happens inside a pentest's live-testing scope.
outputstringyesWhat it hands back to the skill. One of: leads, document.
availablebooleanyesWhether it can run on this server right now.
unavailableReasonstringnoWhy not, when available is false.
permittedbooleanyesWhether this organisation lets skills use it.

#SkillManifest

A skill's settings, read from the frontmatter of its SKILL.md.

FieldTypeAlways presentDescription
idstringyesThe skill's name, which is also its id: lowercase letters, digits and hyphens.
titlestringyesThe display name.
versionstringyesThe skill's own version.
categorystringyesThe part of the catalogue it belongs to. One of: appsec, devsecops, secrets, secure-sdlc, compliance, incident-response.
descriptionstringyesWhat it does and when to use it.
licensestringnoThe licence named in the skill, when it names one.
compatibilitystringnoWhat the skill says it needs, when it says so.
authorstringnoWho wrote it, when the skill says so.
appliesToobjectyesWhen the skill is chosen for a run.
appliesTo.scopestringyesfile: runs over the files that match. repository: runs once for the repository.
appliesTo.pipelinesarray of stringyesWhere it may run. review: pull request reviews. pentest: pentests. live: inside a pentest that has a running target in scope. on-demand: by itself, through the skill-runs routes.
appliesTo.filePatternsarray of stringyesThe files it applies to. Empty means any file.
appliesTo.languagesarray of stringyesThe languages it applies to. Empty means any.
appliesTo.technologiesarray of stringyesThe frameworks and platforms it applies to. Empty means any.
toolsarray of stringyesThe tools the skill asks for.
inputsarray of objectyesWhat a run hands to the skill. An on-demand run must supply every required input: finding means findingId, pull_request means prNumber, text means text, artifacts means two uploads or two refs.
inputs[].namestringyesWhat is handed to the skill. One of: repository, pull_request, finding, findings, threat_model, text, artifacts.
inputs[].requiredbooleanyesWhether a run cannot start without it.
outputobjectyesWhat the skill returns.
output.kindstringyesfindings: candidate leads. document: a written document. triage: a verdict on one existing finding.
output.documentstringnoWhich document, when kind is document.
limitsobjectyesThe ceilings the skill runs under. A custom skill can lower them, never raise them past what the server allows.
limits.tokenSharenumberyesThe largest share of a run's discovery budget the skill may use, from 0 to 1.
limits.timeMinutesintegeryesHow long it may run, in minutes.
limits.maxStepsintegeryesHow many steps it may take.

Nullgap documentation