---
updatedAt: 2026-05-06T16:54:57.000Z
agentTools:
projectIndex: https://docs.censys.com/llms.txt
---
# Create a tag assignment
Assign a tag to an asset. Tag assignments are only visible to members of your organization, depending on the tag's privacy settings. You must have access to the tag to assign it to an asset.
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"
},
"CreateTagAssignmentInputBody": {
"additionalProperties": false,
"properties": {
"asset_id": {
"description": "The identifier of the asset (host IP, certificate SHA-256 fingerprint, or web property hostname:port).",
"examples": [
"8.8.8.8",
"3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf",
"platform.censys.io:443"
],
"type": "string"
}
},
"required": [
"asset_id"
],
"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"
},
"ResponseEnvelopeTagAssignment": {
"additionalProperties": false,
"properties": {
"result": {
"$ref": "#/components/schemas/TagAssignment"
}
},
"type": "object"
},
"TagAssignment": {
"additionalProperties": false,
"properties": {
"asset_id": {
"description": "The identifier of the tagged asset (host IP, certificate SHA-256 fingerprint, or web property domain/IP:port).",
"type": "string"
},
"asset_type": {
"description": "The inferred type of the asset.",
"enum": [
"host",
"certificate",
"web_property",
"unknown"
],
"type": "string"
},
"created_at": {
"description": "RFC3339 timestamp when the assignment was created.",
"format": "date-time",
"type": "string"
},
"created_by": {
"description": "The ID of the user or service account that created the assignment.",
"format": "uuid",
"type": "string"
},
"id": {
"description": "The unique ID of the assignment.",
"format": "uuid",
"type": "string"
},
"platform_ref": {
"description": "A direct URL to the asset in the Censys platform.",
"type": "string"
},
"tag_id": {
"description": "The ID of the tag.",
"format": "uuid",
"type": "string"
}
},
"required": [
"id",
"tag_id",
"asset_id",
"asset_type",
"platform_ref",
"created_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/{tag_id}/assignments": {
"post": {
"description": "Assign a tag to an asset. Tag assignments are only visible to members of your organization, depending on the tag's privacy settings. You must have access to the tag to assign it to an asset.
This endpoint does not cost any credits to execute.",
"operationId": "v3-tags-create-assignment",
"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
},
{
"description": "The ID of the tag to assign.",
"in": "path",
"name": "tag_id",
"required": true,
"schema": {
"description": "The ID of the tag to assign.",
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTagAssignmentInputBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseEnvelopeTagAssignment"
}
}
},
"description": "Tag assignment 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"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Tag not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Tag assignment already exists for this asset"
},
"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 assignment",
"tags": [
"Tags and Comments"
],
"x-speakeasy-name-override": "CreateTagAssignment"
}
}
},
"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"
}
}
]
}
}
```