> For the complete documentation index, see [llms.txt](https://learn.netmaker.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.netmaker.io/api-spec/tag.md).

# TAG

## GET /api/v1/tags

> List Tags in a network

```json
{"openapi":"3.1.1","info":{"title":"NetMaker","version":"1.4.0"},"tags":[],"servers":[{"url":"http://api.demo.netmaker.io"}],"security":[{"oauth":[]}],"paths":{"/api/v1/tags":{"get":{"parameters":[{"schema":{"type":"string"},"description":"Network ID","in":"query","name":"network","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/models.TagListRespNodes"},"type":"array"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"List Tags in a network","tags":["TAG"]}}},"components":{"schemas":{"models.TagListRespNodes":{"properties":{"color_code":{"type":"string"},"created_at":{"type":"string"},"created_by":{"type":"string"},"id":{"type":"string"},"network":{"$ref":"#/components/schemas/models.NetworkID"},"tag_name":{"type":"string"},"tagged_nodes":{"items":{"$ref":"#/components/schemas/models.ApiNode"},"type":"array"},"used_by_count":{"type":"integer"}},"type":"object"},"models.NetworkID":{"enum":["all_networks"],"type":"string"},"models.ApiNode":{"properties":{"additional_rag_ips":{"items":{"type":"string"},"type":"array"},"address":{"type":"string"},"address6":{"type":"string"},"allowedips":{"items":{"type":"string"},"type":"array"},"auto_assign_gw":{"type":"boolean"},"auto_relayed_peers":{"additionalProperties":{"type":"string"},"type":"object"},"connected":{"type":"boolean"},"country":{"type":"string"},"defaultacl":{"description":"== PRO ==","type":"string"},"dnson":{"type":"boolean"},"egressgatewaynatenabled":{"type":"boolean"},"egressgatewayranges":{"items":{"type":"string"},"type":"array"},"egressgatewayranges_with_metric":{"items":{"$ref":"#/components/schemas/models.EgressRangeMetric"},"type":"array"},"expdatetime":{"format":"int64","type":"integer"},"fail_over_peers":{"additionalProperties":{"type":"object"},"type":"object"},"failed_over_by":{"type":"string"},"hostid":{"minLength":5,"type":"string"},"id":{"minLength":5,"type":"string"},"inet_node_req":{"$ref":"#/components/schemas/models.InetNodeReq"},"ingressdns":{"type":"string"},"ingressmtu":{"type":"integer"},"ingresspersistentkeepalive":{"type":"integer"},"internetgw_node_id":{"type":"string"},"is_auto_relay":{"type":"boolean"},"is_fail_over":{"type":"boolean"},"is_gw":{"type":"boolean"},"is_static":{"type":"boolean"},"is_user_node":{"type":"boolean"},"isegressgateway":{"type":"boolean"},"isingressgateway":{"type":"boolean"},"isinternetgateway":{"type":"boolean"},"isrelay":{"type":"boolean"},"isrelayed":{"type":"boolean"},"last_evaluated_at":{"type":"string"},"lastcheckin":{"format":"int64","type":"integer"},"lastmodified":{"format":"int64","type":"integer"},"lastpeerupdate":{"format":"int64","type":"integer"},"localaddress":{"type":"string"},"location":{"type":"string"},"metadata":{"type":"string"},"network":{"type":"string"},"networkrange":{"type":"string"},"networkrange6":{"type":"string"},"pendingdelete":{"type":"boolean"},"posture_check_violation_severity_level":{"$ref":"#/components/schemas/models.Severity"},"posture_check_violations":{"items":{"$ref":"#/components/schemas/models.Violation"},"type":"array"},"relayedby":{"description":"AutoRelayedBy                 uuid.UUID           `json:\"auto_relayed_by\"`","type":"string"},"relaynodes":{"items":{"type":"string"},"type":"array"},"server":{"type":"string"},"static_node":{"$ref":"#/components/schemas/models.ExtClient"},"status":{"$ref":"#/components/schemas/models.NodeStatus"},"tags":{"additionalProperties":{"type":"object"},"type":"object"}},"required":["hostid","id"],"type":"object"},"models.EgressRangeMetric":{"properties":{"nat":{"type":"boolean"},"nat_mode":{"$ref":"#/components/schemas/models.EgressNATMode"},"network":{"type":"string"},"route_metric":{"description":"preffered range 1-999","type":"integer"},"virtual_network":{"type":"string"}},"type":"object"},"models.EgressNATMode":{"enum":["virtual_nat","direct_nat"],"type":"string"},"models.InetNodeReq":{"properties":{"inet_node_client_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"},"models.Severity":{"enum":[0,1,2,3,4],"type":"integer"},"models.Violation":{"properties":{"attribute":{"type":"string"},"check_id":{"type":"string"},"message":{"type":"string"},"name":{"type":"string"},"severity":{"$ref":"#/components/schemas/models.Severity"}},"type":"object"},"models.ExtClient":{"properties":{"address":{"type":"string"},"address6":{"type":"string"},"allowed_ips":{"items":{"type":"string"},"type":"array"},"client_version":{"type":"string"},"clientid":{"type":"string"},"country":{"type":"string"},"deniednodeacls":{"additionalProperties":{"type":"object"},"type":"object"},"device_id":{"type":"string"},"device_name":{"type":"string"},"dns":{"type":"string"},"enabled":{"type":"boolean"},"extraallowedips":{"items":{"type":"string"},"type":"array"},"ingressgatewayendpoint":{"type":"string"},"ingressgatewayid":{"type":"string"},"jit_expires_at":{"description":"JIT grant expiry time (nil if JIT not enabled or user is admin)","type":"string"},"kernel_version":{"type":"string"},"last_evaluated_at":{"type":"string"},"lastmodified":{"format":"int64","type":"integer"},"location":{"description":"format: lat,long","type":"string"},"network":{"type":"string"},"os":{"type":"string"},"os_family":{"type":"string"},"os_version":{"type":"string"},"ownerid":{"type":"string"},"postdown":{"type":"string"},"postup":{"type":"string"},"posture_check_violation_severity_level":{"$ref":"#/components/schemas/models.Severity"},"posture_check_violations":{"items":{"$ref":"#/components/schemas/models.Violation"},"type":"array"},"privatekey":{"type":"string"},"public_endpoint":{"type":"string"},"publickey":{"type":"string"},"remote_access_client_id":{"description":"unique ID (MAC address) of RAC machine","type":"string"},"tags":{"additionalProperties":{"type":"object"},"type":"object"}},"type":"object"},"models.NodeStatus":{"enum":["online","offline","warning","error","unknown","disconnected"],"type":"string"},"models.ErrorResponse":{"properties":{"code":{"type":"integer"},"message":{"type":"string"},"response":{}},"type":"object"}}}}
```

## POST /api/v1/tags

> Create Tag

```json
{"openapi":"3.1.1","info":{"title":"NetMaker","version":"1.4.0"},"tags":[],"servers":[{"url":"http://api.demo.netmaker.io"}],"security":[{"oauth":[]}],"paths":{"/api/v1/tags":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.TagListRespNodes"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"Create Tag","tags":["TAG"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateTagReq"}}},"description":"Tag creation request","required":true}}}},"components":{"schemas":{"models.TagListRespNodes":{"properties":{"color_code":{"type":"string"},"created_at":{"type":"string"},"created_by":{"type":"string"},"id":{"type":"string"},"network":{"$ref":"#/components/schemas/models.NetworkID"},"tag_name":{"type":"string"},"tagged_nodes":{"items":{"$ref":"#/components/schemas/models.ApiNode"},"type":"array"},"used_by_count":{"type":"integer"}},"type":"object"},"models.NetworkID":{"enum":["all_networks"],"type":"string"},"models.ApiNode":{"properties":{"additional_rag_ips":{"items":{"type":"string"},"type":"array"},"address":{"type":"string"},"address6":{"type":"string"},"allowedips":{"items":{"type":"string"},"type":"array"},"auto_assign_gw":{"type":"boolean"},"auto_relayed_peers":{"additionalProperties":{"type":"string"},"type":"object"},"connected":{"type":"boolean"},"country":{"type":"string"},"defaultacl":{"description":"== PRO ==","type":"string"},"dnson":{"type":"boolean"},"egressgatewaynatenabled":{"type":"boolean"},"egressgatewayranges":{"items":{"type":"string"},"type":"array"},"egressgatewayranges_with_metric":{"items":{"$ref":"#/components/schemas/models.EgressRangeMetric"},"type":"array"},"expdatetime":{"format":"int64","type":"integer"},"fail_over_peers":{"additionalProperties":{"type":"object"},"type":"object"},"failed_over_by":{"type":"string"},"hostid":{"minLength":5,"type":"string"},"id":{"minLength":5,"type":"string"},"inet_node_req":{"$ref":"#/components/schemas/models.InetNodeReq"},"ingressdns":{"type":"string"},"ingressmtu":{"type":"integer"},"ingresspersistentkeepalive":{"type":"integer"},"internetgw_node_id":{"type":"string"},"is_auto_relay":{"type":"boolean"},"is_fail_over":{"type":"boolean"},"is_gw":{"type":"boolean"},"is_static":{"type":"boolean"},"is_user_node":{"type":"boolean"},"isegressgateway":{"type":"boolean"},"isingressgateway":{"type":"boolean"},"isinternetgateway":{"type":"boolean"},"isrelay":{"type":"boolean"},"isrelayed":{"type":"boolean"},"last_evaluated_at":{"type":"string"},"lastcheckin":{"format":"int64","type":"integer"},"lastmodified":{"format":"int64","type":"integer"},"lastpeerupdate":{"format":"int64","type":"integer"},"localaddress":{"type":"string"},"location":{"type":"string"},"metadata":{"type":"string"},"network":{"type":"string"},"networkrange":{"type":"string"},"networkrange6":{"type":"string"},"pendingdelete":{"type":"boolean"},"posture_check_violation_severity_level":{"$ref":"#/components/schemas/models.Severity"},"posture_check_violations":{"items":{"$ref":"#/components/schemas/models.Violation"},"type":"array"},"relayedby":{"description":"AutoRelayedBy                 uuid.UUID           `json:\"auto_relayed_by\"`","type":"string"},"relaynodes":{"items":{"type":"string"},"type":"array"},"server":{"type":"string"},"static_node":{"$ref":"#/components/schemas/models.ExtClient"},"status":{"$ref":"#/components/schemas/models.NodeStatus"},"tags":{"additionalProperties":{"type":"object"},"type":"object"}},"required":["hostid","id"],"type":"object"},"models.EgressRangeMetric":{"properties":{"nat":{"type":"boolean"},"nat_mode":{"$ref":"#/components/schemas/models.EgressNATMode"},"network":{"type":"string"},"route_metric":{"description":"preffered range 1-999","type":"integer"},"virtual_network":{"type":"string"}},"type":"object"},"models.EgressNATMode":{"enum":["virtual_nat","direct_nat"],"type":"string"},"models.InetNodeReq":{"properties":{"inet_node_client_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"},"models.Severity":{"enum":[0,1,2,3,4],"type":"integer"},"models.Violation":{"properties":{"attribute":{"type":"string"},"check_id":{"type":"string"},"message":{"type":"string"},"name":{"type":"string"},"severity":{"$ref":"#/components/schemas/models.Severity"}},"type":"object"},"models.ExtClient":{"properties":{"address":{"type":"string"},"address6":{"type":"string"},"allowed_ips":{"items":{"type":"string"},"type":"array"},"client_version":{"type":"string"},"clientid":{"type":"string"},"country":{"type":"string"},"deniednodeacls":{"additionalProperties":{"type":"object"},"type":"object"},"device_id":{"type":"string"},"device_name":{"type":"string"},"dns":{"type":"string"},"enabled":{"type":"boolean"},"extraallowedips":{"items":{"type":"string"},"type":"array"},"ingressgatewayendpoint":{"type":"string"},"ingressgatewayid":{"type":"string"},"jit_expires_at":{"description":"JIT grant expiry time (nil if JIT not enabled or user is admin)","type":"string"},"kernel_version":{"type":"string"},"last_evaluated_at":{"type":"string"},"lastmodified":{"format":"int64","type":"integer"},"location":{"description":"format: lat,long","type":"string"},"network":{"type":"string"},"os":{"type":"string"},"os_family":{"type":"string"},"os_version":{"type":"string"},"ownerid":{"type":"string"},"postdown":{"type":"string"},"postup":{"type":"string"},"posture_check_violation_severity_level":{"$ref":"#/components/schemas/models.Severity"},"posture_check_violations":{"items":{"$ref":"#/components/schemas/models.Violation"},"type":"array"},"privatekey":{"type":"string"},"public_endpoint":{"type":"string"},"publickey":{"type":"string"},"remote_access_client_id":{"description":"unique ID (MAC address) of RAC machine","type":"string"},"tags":{"additionalProperties":{"type":"object"},"type":"object"}},"type":"object"},"models.NodeStatus":{"enum":["online","offline","warning","error","unknown","disconnected"],"type":"string"},"models.ErrorResponse":{"properties":{"code":{"type":"integer"},"message":{"type":"string"},"response":{}},"type":"object"},"models.CreateTagReq":{"properties":{"color_code":{"type":"string"},"network":{"$ref":"#/components/schemas/models.NetworkID"},"tag_name":{"type":"string"},"tagged_nodes":{"items":{"$ref":"#/components/schemas/models.ApiNode"},"type":"array"}},"type":"object"}}}}
```

## PUT /api/v1/tags

> Update Tag

```json
{"openapi":"3.1.1","info":{"title":"NetMaker","version":"1.4.0"},"tags":[],"servers":[{"url":"http://api.demo.netmaker.io"}],"security":[{"oauth":[]}],"paths":{"/api/v1/tags":{"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.TagListRespNodes"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"Update Tag","tags":["TAG"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.UpdateTagReq"}}},"description":"Tag update request","required":true}}}},"components":{"schemas":{"models.TagListRespNodes":{"properties":{"color_code":{"type":"string"},"created_at":{"type":"string"},"created_by":{"type":"string"},"id":{"type":"string"},"network":{"$ref":"#/components/schemas/models.NetworkID"},"tag_name":{"type":"string"},"tagged_nodes":{"items":{"$ref":"#/components/schemas/models.ApiNode"},"type":"array"},"used_by_count":{"type":"integer"}},"type":"object"},"models.NetworkID":{"enum":["all_networks"],"type":"string"},"models.ApiNode":{"properties":{"additional_rag_ips":{"items":{"type":"string"},"type":"array"},"address":{"type":"string"},"address6":{"type":"string"},"allowedips":{"items":{"type":"string"},"type":"array"},"auto_assign_gw":{"type":"boolean"},"auto_relayed_peers":{"additionalProperties":{"type":"string"},"type":"object"},"connected":{"type":"boolean"},"country":{"type":"string"},"defaultacl":{"description":"== PRO ==","type":"string"},"dnson":{"type":"boolean"},"egressgatewaynatenabled":{"type":"boolean"},"egressgatewayranges":{"items":{"type":"string"},"type":"array"},"egressgatewayranges_with_metric":{"items":{"$ref":"#/components/schemas/models.EgressRangeMetric"},"type":"array"},"expdatetime":{"format":"int64","type":"integer"},"fail_over_peers":{"additionalProperties":{"type":"object"},"type":"object"},"failed_over_by":{"type":"string"},"hostid":{"minLength":5,"type":"string"},"id":{"minLength":5,"type":"string"},"inet_node_req":{"$ref":"#/components/schemas/models.InetNodeReq"},"ingressdns":{"type":"string"},"ingressmtu":{"type":"integer"},"ingresspersistentkeepalive":{"type":"integer"},"internetgw_node_id":{"type":"string"},"is_auto_relay":{"type":"boolean"},"is_fail_over":{"type":"boolean"},"is_gw":{"type":"boolean"},"is_static":{"type":"boolean"},"is_user_node":{"type":"boolean"},"isegressgateway":{"type":"boolean"},"isingressgateway":{"type":"boolean"},"isinternetgateway":{"type":"boolean"},"isrelay":{"type":"boolean"},"isrelayed":{"type":"boolean"},"last_evaluated_at":{"type":"string"},"lastcheckin":{"format":"int64","type":"integer"},"lastmodified":{"format":"int64","type":"integer"},"lastpeerupdate":{"format":"int64","type":"integer"},"localaddress":{"type":"string"},"location":{"type":"string"},"metadata":{"type":"string"},"network":{"type":"string"},"networkrange":{"type":"string"},"networkrange6":{"type":"string"},"pendingdelete":{"type":"boolean"},"posture_check_violation_severity_level":{"$ref":"#/components/schemas/models.Severity"},"posture_check_violations":{"items":{"$ref":"#/components/schemas/models.Violation"},"type":"array"},"relayedby":{"description":"AutoRelayedBy                 uuid.UUID           `json:\"auto_relayed_by\"`","type":"string"},"relaynodes":{"items":{"type":"string"},"type":"array"},"server":{"type":"string"},"static_node":{"$ref":"#/components/schemas/models.ExtClient"},"status":{"$ref":"#/components/schemas/models.NodeStatus"},"tags":{"additionalProperties":{"type":"object"},"type":"object"}},"required":["hostid","id"],"type":"object"},"models.EgressRangeMetric":{"properties":{"nat":{"type":"boolean"},"nat_mode":{"$ref":"#/components/schemas/models.EgressNATMode"},"network":{"type":"string"},"route_metric":{"description":"preffered range 1-999","type":"integer"},"virtual_network":{"type":"string"}},"type":"object"},"models.EgressNATMode":{"enum":["virtual_nat","direct_nat"],"type":"string"},"models.InetNodeReq":{"properties":{"inet_node_client_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"},"models.Severity":{"enum":[0,1,2,3,4],"type":"integer"},"models.Violation":{"properties":{"attribute":{"type":"string"},"check_id":{"type":"string"},"message":{"type":"string"},"name":{"type":"string"},"severity":{"$ref":"#/components/schemas/models.Severity"}},"type":"object"},"models.ExtClient":{"properties":{"address":{"type":"string"},"address6":{"type":"string"},"allowed_ips":{"items":{"type":"string"},"type":"array"},"client_version":{"type":"string"},"clientid":{"type":"string"},"country":{"type":"string"},"deniednodeacls":{"additionalProperties":{"type":"object"},"type":"object"},"device_id":{"type":"string"},"device_name":{"type":"string"},"dns":{"type":"string"},"enabled":{"type":"boolean"},"extraallowedips":{"items":{"type":"string"},"type":"array"},"ingressgatewayendpoint":{"type":"string"},"ingressgatewayid":{"type":"string"},"jit_expires_at":{"description":"JIT grant expiry time (nil if JIT not enabled or user is admin)","type":"string"},"kernel_version":{"type":"string"},"last_evaluated_at":{"type":"string"},"lastmodified":{"format":"int64","type":"integer"},"location":{"description":"format: lat,long","type":"string"},"network":{"type":"string"},"os":{"type":"string"},"os_family":{"type":"string"},"os_version":{"type":"string"},"ownerid":{"type":"string"},"postdown":{"type":"string"},"postup":{"type":"string"},"posture_check_violation_severity_level":{"$ref":"#/components/schemas/models.Severity"},"posture_check_violations":{"items":{"$ref":"#/components/schemas/models.Violation"},"type":"array"},"privatekey":{"type":"string"},"public_endpoint":{"type":"string"},"publickey":{"type":"string"},"remote_access_client_id":{"description":"unique ID (MAC address) of RAC machine","type":"string"},"tags":{"additionalProperties":{"type":"object"},"type":"object"}},"type":"object"},"models.NodeStatus":{"enum":["online","offline","warning","error","unknown","disconnected"],"type":"string"},"models.ErrorResponse":{"properties":{"code":{"type":"integer"},"message":{"type":"string"},"response":{}},"type":"object"},"models.UpdateTagReq":{"properties":{"color_code":{"type":"string"},"created_at":{"type":"string"},"created_by":{"type":"string"},"id":{"type":"string"},"network":{"$ref":"#/components/schemas/models.NetworkID"},"new_name":{"type":"string"},"tag_name":{"type":"string"},"tagged_nodes":{"items":{"$ref":"#/components/schemas/models.ApiNode"},"type":"array"}},"type":"object"}}}}
```

## DELETE /api/v1/tags

> Delete Tag

```json
{"openapi":"3.1.1","info":{"title":"NetMaker","version":"1.4.0"},"tags":[],"servers":[{"url":"http://api.demo.netmaker.io"}],"security":[{"oauth":[]}],"paths":{"/api/v1/tags":{"delete":{"parameters":[{"schema":{"type":"string"},"description":"Tag ID to delete","in":"query","name":"tag_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.SuccessResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"Delete Tag","tags":["TAG"]}}},"components":{"schemas":{"models.SuccessResponse":{"properties":{"code":{"type":"integer"},"message":{"type":"string"},"response":{}},"type":"object"},"models.ErrorResponse":{"properties":{"code":{"type":"integer"},"message":{"type":"string"},"response":{}},"type":"object"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://learn.netmaker.io/api-spec/tag.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.