---
updatedAt: 2026-05-06T16:54:57.000Z
agentTools:
projectIndex: https://docs.censys.com/llms.txt
---
# Create a tag
Create a new tag in your organization. Tags can be used to label and organize assets.
Specify a privacy setting to control visibility: `private` tags are only visible to you and organization admins, while `shared` tags are visible and manageable by all organization members.
Tag names must be unique within your organization.
This endpoint does not cost any credits to execute.
# OpenAPI definition
```json
{
"components": {
"schemas": {
"AuthenticationError": {
"additionalProperties": false,
"properties": {
"error": {
"$ref": "#/components/schemas/AuthenticationErrorDetail",
"description": "Detailed information about the authentication error"
}
},
"type": "object"
},
"AuthenticationErrorDetail": {
"additionalProperties": false,
"properties": {
"code": {
"description": "HTTP status code",
"examples": [
401
],
"format": "int64",
"type": "integer"
},
"message": {
"description": "Human-readable message describing the error occurrence",
"examples": [
"Access credentials are invalid"
],
"type": "string"
},
"reason": {
"description": "Human-readable explanation of the underlying cause of the error",
"examples": [
"Access token is not active"
],
"type": "string"
},
"request": {
"type": "string"
},
"status": {
"description": "HTTP status message associated with the error",
"examples": [
"Unauthorized"
],
"type": "string"
}
},
"type": "object"
},
"CreateTagInputBody": {
"additionalProperties": false,
"properties": {
"description": {
"description": "A human-readable description of the tag.",
"maxLength": 1000,
"type": "string"
},
"name": {
"description": "The display name of the tag. Must be unique within the organization.",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"privacy": {
"description": "Tag visibility and management settings. `private` tags are only visible to and editable by organization admins. `shared` tags are visible to and editable by all organization members.",
"enum": [
"private",
"shared"
],
"type": "string"
}
},
"required": [
"name",
"privacy"
],
"type": "object"
},
"ErrorDetail": {
"additionalProperties": false,
"properties": {
"location": {
"description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'",
"type": "string"
},
"message": {
"description": "Error message text",
"type": "string"
},
"value": {
"description": "The value at the given location"
}
},
"type": "object"
},
"ErrorModel": {
"additionalProperties": false,
"properties": {
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"examples": [
"Property foo is required but is missing."
],
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"type": [
"array",
"null"
]
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"examples": [
"https://example.com/error-log/abc123"
],
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"examples": [
400
],
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"examples": [
"Bad Request"
],
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"examples": [
"https://example.com/errors/example"
],
"format": "uri",
"type": "string"
}
},
"type": "object"
},
"ResponseEnvelopeTag": {
"additionalProperties": false,
"properties": {
"result": {
"$ref": "#/components/schemas/Tag"
}
},
"type": "object"
},
"Tag": {
"additionalProperties": false,
"properties": {
"created_at": {
"description": "RFC3339 timestamp when the tag was created.",
"format": "date-time",
"type": "string"
},
"created_by": {
"description": "The ID of the user or service account that created the tag.",
"format": "uuid",
"type": "string"
},
"description": {
"description": "A human-readable description of the tag.",
"type": "string"
},
"id": {
"description": "The unique ID of the tag.",
"format": "uuid",
"type": "string"
},
"name": {
"description": "The display name of the tag.",
"type": "string"
},
"privacy": {
"description": "Tag visibility and management settings. `private` tags are only visible to and editable by organization admins. `shared` tags are visible to and editable by all organization members.",
"enum": [
"private",
"shared"
],
"type": "string"
},
"updated_at": {
"description": "RFC3339 timestamp when the tag was last updated.",
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"name",
"privacy",
"created_at",
"updated_at",
"created_by"
],
"type": "object"
}
},
"securitySchemes": {
"PersonalAccessToken": {
"description": "Your Censys personal access token. These are managed in your [Account Settings](https://accounts.censys.io/settings/personal-access-tokens)",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"contact": {
"email": "support@censys.com",
"name": "Censys Inc.",
"url": "https://censys.com"
},
"title": "Censys Platform API",
"version": "1.0.151"
},
"openapi": "3.1.0",
"paths": {
"/v3/tags": {
"post": {
"description": "Create a new tag in your organization. Tags can be used to label and organize assets.
Specify a privacy setting to control visibility: `private` tags are only visible to you and organization admins, while `shared` tags are visible and manageable by all organization members.
Tag names must be unique within your organization.
This endpoint does not cost any credits to execute.",
"operationId": "v3-tags-create-tag",
"parameters": [
{
"description": "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.",
"explode": false,
"in": "query",
"name": "organization_id",
"required": true,
"schema": {
"description": "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.",
"examples": [
"11111111-2222-3333-4444-555555555555"
],
"format": "uuid",
"type": "string"
}
},
{
"description": "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.",
"in": "header",
"name": "X-Organization-ID",
"schema": {
"description": "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.",
"examples": [
"11111111-2222-3333-4444-555555555555"
],
"format": "uuid",
"type": "string"
},
"x-speakeasy-ignore": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTagInputBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseEnvelopeTag"
}
}
},
"description": "Tag created successfully",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
},
"X-Request-ID": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationError"
}
}
},
"description": "Request does not contain a valid Authorization token"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "User does not have permission to access this data"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Tag name already exists in this organization"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Invalid input"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Internal server error"
}
},
"security": [
{
"PersonalAccessToken": []
}
],
"summary": "Create a tag",
"tags": [
"Tags and Comments"
],
"x-speakeasy-name-override": "CreateTag"
}
}
},
"servers": [
{
"description": "The Censys Platform API",
"url": "https://api.platform.censys.io"
}
],
"tags": [
{
"description": "Endpoints related to asset tagging and commenting",
"name": "Tags and Comments"
}
],
"x-readme": {
"parameter-ordering": [
"path",
"body",
"query",
"cookie",
"form",
"header"
],
"samples-languages": [
"shell",
"python",
"go",
"javascript",
"java"
]
},
"x-speakeasy-globals": {
"parameters": [
{
"in": "query",
"name": "organization_id",
"schema": {
"type": "string"
}
}
]
}
}
```