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.
| Operation | Method and path | Who may call it |
|---|---|---|
| List skills | GET /api/orgs/{org}/skills | read |
| Add a custom skill | POST /api/orgs/{org}/skills | admin |
| Check a skill without saving it | POST /api/orgs/{org}/skills/validate | write |
| Upload a skill folder | POST /api/orgs/{org}/skills/import | admin |
| Set permitted tools, repository overrides and the pentest switch | PUT /api/orgs/{org}/skills/settings | admin |
| Get a skill | GET /api/orgs/{org}/skills/{id} | read |
| Replace a custom skill | PUT /api/orgs/{org}/skills/{id} | admin |
| Remove a custom skill | DELETE /api/orgs/{org}/skills/{id} | admin |
| Switch a skill on | POST /api/orgs/{org}/skills/{id}/enable | admin |
| Switch a skill off | POST /api/orgs/{org}/skills/{id}/disable | admin |
#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
| 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/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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
skillMd | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | invalid_skill | The 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. |
| 409 | duplicate_name | The organisation already has a custom skill with that name. Change it with PUT, or choose another name. |
| 409 | limit_reached | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
skillMd | string | yes | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | invalid_skill | The 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. |
| 400 | bad_archive | The upload is damaged, is neither a zip nor a gzip-compressed tar, holds more than 200 files, or unpacks to more than it may. |
| 400 | bad_request | The upload is empty. |
| 409 | duplicate_name | The organisation already has a custom skill with that name. |
| 409 | limit_reached | The organisation already keeps 40 custom skills. Remove one first. |
| 413 | too_large | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
allowedTools | array of string or null | no | The tools skills may use. Null lifts the restriction: every tool this server has. |
repositories | object | no | Repository id to the skills forced on and off there. Up to 500 repositories. |
builtinInPentests | boolean | no | Run 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
| Status | Code | When |
|---|---|---|
| 400 | bad_request | allowedTools 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The skill id: the name in its SKILL.md. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
skillMd | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | invalid_skill | The 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. |
| 403 | forbidden | The id is a built-in skill. A built-in skill cannot be edited: switch it off, or write a custom skill under another name. |
| 404 | not_found | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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)
| Field | Type | Always present | Description |
|---|---|---|---|
ok | boolean | yes | Always true. |
{
"ok": true
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The id is a built-in skill. A built-in skill cannot be removed: switch it off instead. |
| 404 | not_found | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The skill id: the name in its SKILL.md. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
repoId | string or null | no | A 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The skill id: the name in its SKILL.md. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
repoId | string or null | no | A 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | The organisation has no skill with that id, or no repository with the repoId sent. |
| 400 | always_on | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
skills | array of SkillSummary | yes | Every skill the organisation can use: the built-in catalogue and its own, switched on or not. |
tools | array of SkillToolInfo | yes | Every tool a skill can name, with whether it is installed and permitted here. |
settings | SkillSettings | yes | |
categories | array of object | yes | The categories, in the order the console shows them. |
categories[].id | string | yes | The category id. One of: appsec, devsecops, secrets, secure-sdlc, compliance, incident-response. |
categories[].title | string | yes | Its display name. |
limits | object | yes | The limits skills are held to. |
limits.customSkills | integer | yes | Custom skills an organisation can keep. |
limits.importBytes | integer | yes | Largest uploaded skill folder, in bytes. |
limits.importFiles | integer | yes | Most files an uploaded skill folder may hold. |
limits.artifactBytes | integer | yes | Largest file uploaded for a comparison, in bytes. |
limits.artifacts | integer | yes | Uploads for a comparison an organisation can keep at a time. |
limits.textChars | integer | yes | Longest text given to a run, in characters. |
limits.skillMdChars | integer | yes | Longest SKILL.md, in characters. |
about | string | yes | How a skill differs from a custom check, in a sentence to show to people. |
#SkillDetail
One skill with its full text.
| Field | Type | Always present | Description |
|---|---|---|---|
manifest | SkillManifest | yes | |
origin | string | yes | built-in: part of the catalogue that ships with Nullgap. custom: written or uploaded by this organisation. |
enabled | boolean | yes | Whether the skill is on for the organisation. A repository can still override this either way; see settings.repositories in the catalogue answer. |
tools | array of object | yes | The 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[].id | string | yes | A 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[].available | boolean | yes | Whether the tool can run on this server right now. |
tools[].permitted | boolean | yes | Whether the organisation lets skills use it. |
custom | object | no | Present on custom skills only. |
custom.createdBy | string | yes | Who first saved it: an e-mail address, or the name of an API key. |
custom.updatedAt | string | yes | When it was last saved. |
custom.imported | boolean | yes | True when it came from an uploaded skill folder rather than from text sent to the API or typed in the console. |
custom.otherFiles | array of object | yes | Files 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[].path | string | yes | The file's path inside the uploaded folder. |
custom.otherFiles[].bytes | integer | yes | Its size in bytes. |
custom.note | string or null | yes | What the hosted product does not do with a custom skill, in a sentence to show next to it. |
skillMd | string | yes | The whole SKILL.md, frontmatter included. |
#SkillValidation
The result of checking a SKILL.md without saving it.
| Field | Type | Always present | Description |
|---|---|---|---|
ok | boolean | yes | True when the text would be accepted as a custom skill. |
errors | array of string | yes | Why it would be refused. Empty when ok is true. |
warnings | array of string | yes | Things that do not stop it being saved but will not work as written. Empty when ok is false. |
manifest | SkillManifest | no | The settings read from the text, when ok is true. |
#SkillSettings
The organisation's choices about skills.
| Field | Type | Always present | Description |
|---|---|---|---|
disabled | array of string | yes | Skills switched off for the whole organisation. Every other skill is on. |
repositories | object | yes | Per repository id: skills forced on or off there, whatever the organisation's own switch says. A repository with no override is not listed. |
allowedTools | array of string or null | yes | The tools skills may use in this organisation. Null means every tool this server has. |
builtinInPentests | boolean | yes | Whether 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.
| Field | Type | Always present | Description |
|---|---|---|---|
manifest | SkillManifest | yes | |
origin | string | yes | built-in: part of the catalogue that ships with Nullgap. custom: written or uploaded by this organisation. |
enabled | boolean | yes | Whether the skill is on for the organisation. A repository can still override this either way; see settings.repositories in the catalogue answer. |
tools | array of object | yes | The 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[].id | string | yes | A 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[].available | boolean | yes | Whether the tool can run on this server right now. |
tools[].permitted | boolean | yes | Whether the organisation lets skills use it. |
custom | object | no | Present on custom skills only. |
custom.createdBy | string | yes | Who first saved it: an e-mail address, or the name of an API key. |
custom.updatedAt | string | yes | When it was last saved. |
custom.imported | boolean | yes | True when it came from an uploaded skill folder rather than from text sent to the API or typed in the console. |
custom.otherFiles | array of object | yes | Files 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[].path | string | yes | The file's path inside the uploaded folder. |
custom.otherFiles[].bytes | integer | yes | Its size in bytes. |
custom.note | string or null | yes | What 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | A 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. |
title | string | yes | The display name. |
description | string | yes | What it does. |
kind | string | yes | built-in: part of Nullgap itself. external: a scanner the operator of the server installs. |
network | string | yes | none: 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. |
output | string | yes | What it hands back to the skill. One of: leads, document. |
available | boolean | yes | Whether it can run on this server right now. |
unavailableReason | string | no | Why not, when available is false. |
permitted | boolean | yes | Whether this organisation lets skills use it. |
#SkillManifest
A skill's settings, read from the frontmatter of its SKILL.md.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The skill's name, which is also its id: lowercase letters, digits and hyphens. |
title | string | yes | The display name. |
version | string | yes | The skill's own version. |
category | string | yes | The part of the catalogue it belongs to. One of: appsec, devsecops, secrets, secure-sdlc, compliance, incident-response. |
description | string | yes | What it does and when to use it. |
license | string | no | The licence named in the skill, when it names one. |
compatibility | string | no | What the skill says it needs, when it says so. |
author | string | no | Who wrote it, when the skill says so. |
appliesTo | object | yes | When the skill is chosen for a run. |
appliesTo.scope | string | yes | file: runs over the files that match. repository: runs once for the repository. |
appliesTo.pipelines | array of string | yes | Where 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.filePatterns | array of string | yes | The files it applies to. Empty means any file. |
appliesTo.languages | array of string | yes | The languages it applies to. Empty means any. |
appliesTo.technologies | array of string | yes | The frameworks and platforms it applies to. Empty means any. |
tools | array of string | yes | The tools the skill asks for. |
inputs | array of object | yes | What 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[].name | string | yes | What is handed to the skill. One of: repository, pull_request, finding, findings, threat_model, text, artifacts. |
inputs[].required | boolean | yes | Whether a run cannot start without it. |
output | object | yes | What the skill returns. |
output.kind | string | yes | findings: candidate leads. document: a written document. triage: a verdict on one existing finding. |
output.document | string | no | Which document, when kind is document. |
limits | object | yes | The ceilings the skill runs under. A custom skill can lower them, never raise them past what the server allows. |
limits.tokenShare | number | yes | The largest share of a run's discovery budget the skill may use, from 0 to 1. |
limits.timeMinutes | integer | yes | How long it may run, in minutes. |
limits.maxSteps | integer | yes | How many steps it may take. |
Nullgap documentation