Skip to content

Applications: Tags, Owners and Bindings

Tags label applications (targets) so you can group and filter them. Each application can also have an owner: a person (owner_id), a team (owner_group_id), or both. Base URL: https://api.nightviz.ai/api/v1/. See the API overview for authentication.

A tag has a name (required, up to 50 characters), an optional key (up to 40 characters), a description, a color and an icon.

  • color: gray, red, orange, amber, green, teal, blue, indigo, purple, pink
  • icon: tag, shield, lock, credit-card, globe, building, users, code, cloud, server, database, flag, star, heart-pulse, briefcase

GET /tags/

Lists the tags in the active organization. Query parameters:

  • filter: case-insensitive search. A plain term matches the key or name. key: name (or key:) narrows to tags whose key starts with key and whose name contains name.
  • order: name, created_at or targets_count, with a leading - for descending.
  • page, page_size
Terminal window
curl -H "Authorization: Token $NIGHTVISION_TOKEN" \
"https://api.nightviz.ai/api/v1/tags/?filter=team&order=-targets_count"
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "00000000-0000-4000-8000-000000000001",
"organization_id": "00000000-0000-4000-8000-0000000000aa",
"key": "team",
"name": "Platform",
"description": null,
"color": "blue",
"icon": "tag",
"targets_count": 3,
"created_by": null,
"created_at": "2026-01-15T10:00:00Z",
"last_updated_at": "2026-01-15T10:00:00Z"
}
]
}

created_by is the creating user’s profile object, or null.

  • POST /tags/ creates one tag (a single object, not an array). Returns 201.
  • GET /tags/{id}/ returns a tag.
  • PUT /tags/{id}/ replaces a tag’s fields. name is required.
  • DELETE /tags/{id}/ deletes the tag and removes it from every application that carried it. Returns 204.
Terminal window
curl -X POST -H "Authorization: Token $NIGHTVISION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key": "team", "name": "Platform", "color": "blue", "icon": "tag"}' \
https://api.nightviz.ai/api/v1/tags/

The response is the tag object shown above.

POST /tags/{id}/assign-to-targets/

Puts the tag on up to 500 applications of the tag’s organization. Request body: targets, an array of application ids.

Terminal window
curl -X POST -H "Authorization: Token $NIGHTVISION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"targets": ["00000000-0000-4000-8000-000000000010", "00000000-0000-4000-8000-000000000011"]}' \
https://api.nightviz.ai/api/v1/tags/00000000-0000-4000-8000-000000000001/assign-to-targets/
{
"results": [
{
"target_id": "00000000-0000-4000-8000-000000000010",
"status": "updated",
"reason": null
},
{
"target_id": "00000000-0000-4000-8000-000000000011",
"status": "skipped",
"reason": "no_permission"
}
]
}

There is one row per requested application, in request order. status is updated, unchanged (the application already had the tag) or skipped. A skipped row has a reason: no_permission (the application does not exist, you cannot see it, or you may not change it) or other_organization.

POST /tags/{id}/remove-from-targets/

Same request and response as assign-to-targets. An application that does not have the tag comes back as unchanged.

PUT /targets/{id}/tags/

Sets the application’s tags to exactly the ids given; an empty list clears them. Every tag must belong to the application’s organization, otherwise the request fails with a 400 on tags.

Terminal window
curl -X PUT -H "Authorization: Token $NIGHTVISION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"tags": ["00000000-0000-4000-8000-000000000001"]}' \
https://api.nightviz.ai/api/v1/targets/00000000-0000-4000-8000-000000000010/tags/
{
"tags": [
{
"id": "00000000-0000-4000-8000-000000000001",
"key": "team",
"name": "Platform",
"color": "blue",
"icon": "tag"
}
]
}

Applications also carry their tags as tags (the same four-field objects plus id) when you read a target.

Set the owner when you create or update a target with these request fields:

  • owner_id: the id of a person, or null.
  • owner_group_id: the id of a team, or null.

A target response includes owner (id, name, email), owner_group (id, name), owner_id, owner_group_id and owner_is_former_member.

Terminal window
curl -X PUT -H "Authorization: Token $NIGHTVISION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"owner_group_id": "00000000-0000-4000-8000-000000000020"}' \
https://api.nightviz.ai/api/v1/targets/00000000-0000-4000-8000-000000000010/

Fields you leave out of the update body are not changed. Send null to clear an owner.

GET /targets/ accepts these additional filters:

  • tag: only applications that have every tag given (ids). Repeat the parameter for more than one.
  • owner: a user id, me for the caller, or none for applications with no owner (no person and no team).
  • owner_group: only applications owned by this team (id).
  • order=team (or -team): sort by the owning team’s name, else the owner’s name, with unowned applications last.
Terminal window
curl -H "Authorization: Token $NIGHTVISION_TOKEN" \
"https://api.nightviz.ai/api/v1/targets/?owner=me&tag=00000000-0000-4000-8000-000000000001"

These list endpoints return exactly the values the owner fields accept. All take search and the usual pagination parameters.

Method and pathReturns
GET /organization/owner-group-candidates/Teams that can own an application in the active organization.
GET /targets/{id}/owner-group-candidates/Teams that can own this application.
GET /organization/owner-candidates/Active members who can own an application or be assigned a finding.
GET /targets/{id}/owner-candidates/Active members who can own this application.
Terminal window
curl -H "Authorization: Token $NIGHTVISION_TOKEN" \
"https://api.nightviz.ai/api/v1/organization/owner-group-candidates/?search=plat"
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "00000000-0000-4000-8000-000000000020",
"name": "Platform",
"member_count": 8
}
]
}

Owner candidates look like this:

{
"id": "00000000-0000-4000-8000-000000000030",
"name": "Alex Example",
"email": "alex@example.com"
}

The organization-wide owner-candidates list needs permission to change applications in at least one project. The per-application lists need permission to change that application.

POST /targets/{id}/move/

Moves an application to another project in the same organization, along with its scans, findings and assignments. Request body: project_id. Returns the updated target. Needs permission to delete the application in its current project and to add applications in the destination.

Terminal window
curl -X POST -H "Authorization: Token $NIGHTVISION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"project_id": "00000000-0000-4000-8000-000000000040"}' \
https://api.nightviz.ai/api/v1/targets/00000000-0000-4000-8000-000000000010/move/

The move returns 400 if the project is in another organization, does not exist for you, or already has an application with the same name. It returns 409 (move_blocked) while the application has authentication, a schedule (enabled or not) or a custom Nuclei template attached; the response lists them. Remove or reassign those first.

Bindings: which page elements call which endpoints

Section titled “Bindings: which page elements call which endpoints”

GET /targets/{id}/network-analysis/bindings/

When NightVision crawls an application, it can record which elements on each page (a button, a form, a link) trigger which API calls. Each entry in the response is one such binding: the element, the event that fires it, and the calls it makes (method and path template). Use it to see which endpoints your interface actually reaches and whether each call matches an endpoint the application declares. There are no query parameters. Needs the same permission as viewing the application.

Terminal window
curl -H "Authorization: Token $NIGHTVISION_TOKEN" \
https://api.nightviz.ai/api/v1/targets/00000000-0000-4000-8000-000000000010/network-analysis/bindings/
{
"target_id": "00000000-0000-4000-8000-000000000010",
"scan_id": "00000000-0000-4000-8000-000000000060",
"scan_ended_at": "2026-03-01T08:00:00Z",
"stored_at": "2026-03-01T08:30:00Z",
"entries": [
{
"id": "binding-1",
"where": "/checkout",
"selector": "button#place-order",
"event": "click",
"confidence": "high",
"calls_state": "list",
"calls": [
{"method": "POST", "path": "/api/orders"}
],
"declared": true,
"firings_total": 4,
"crawls": ["crawl-1"],
"via": null,
"last_scan_id": "00000000-0000-4000-8000-000000000060",
"last_seen": "2026-03-01T08:00:00Z"
}
]
}
  • scan_id and scan_ended_at identify the scan the data comes from, and are null when there is no analysis yet (entries is then empty).
  • calls_state is list (calls were observed), none (the element fired no calls) or unobserved.
  • declared is whether the calls match a declared endpoint.
  • firings_total is how often crawls saw the element fire, and crawls lists the crawls that saw it.

POST /targets/{id}/network-analysis/run/

Analyzes the application’s newest finished crawl immediately and updates its bindings. Needs permission to change the application. It returns 200 when the analysis is started and 204 when there is nothing to analyze, for example when the application has no successful scan yet or its latest scan was already analyzed.

Terminal window
curl -X POST -H "Authorization: Token $NIGHTVISION_TOKEN" \
https://api.nightviz.ai/api/v1/targets/00000000-0000-4000-8000-000000000010/network-analysis/run/