--- updatedAt: 2026-09-24T14:59:35.000Z agentTools: projectIndex: https://virustotal.readme.io/llms.txt --- # Create a new collection > 🚧 IoC scanning and dataset inclusion > > Any IoC submitted or queried via the API will be scanned and added to the VirusTotal dataset, making it accessible to the community. Do not submit or query indicators containing sensitive, confidential, or personally identifiable information (PII). Use this endpoint to create new collections. In the request body, send a collection object containing its name, description and the elements it will contain (for URLs you can either use the URL or its ID). All IOCs must be described as relationships of a newly created Collection object. This is an example request body: ```json Create a collection from relationship descriptors { "data": { "attributes": { "name": "Test collection", "description": "This is how to create a new collection via API." }, "relationships": { "domains": { "data": [ { "type": "domain", "id": "www.virustotal.com" }, { "type": "domain", "id": "www.hooli.com" } ] }, "urls": { "data": [ { "type": "url", "url": "https://www.virustotal.com/" }, { "type": "url", "id": "f11f7cc900638fae209f68498a90158fbfb067fc4191549ddb657e39cc4428c2" } ] }, "ip_addresses": { "data": [ { "type": "ip_address", "id": "8.8.8.8" } ] }, "files": { "data": [ { "type": "file", "id": "ecc0f2aa29b102bf8d67b7d7173e8698c0341ddfdf9757be17595460fbf1791a" } ] } }, "type": "collection" } } ``` ```json Create a collection from raw text { "data": { "attributes": { "name": "Test collection", "description": "This is how to create a new collection via API." }, "raw_items": "This is a text containing an IoC, www.virustotal.com", "type": "collection" } } ``` To modify the collection's attributes or add more elements to a collection using a raw text, refer to the [PATCH/collections/{id}](https://virustotal.readme.io/reference/collections-update) endpoint.\ To add new elements to the collection refer to the [POST /collections/{id}/{relationship}](https://virustotal.readme.io/reference/collections-add-element) endpoint.\ To remove elements from the collection refer to the [DELETE /collections/{id}/{relationship}](https://virustotal.readme.io/reference/collections-delete-element) endpoint. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "virustotal-api-v3", "version": "3.0" }, "servers": [ { "url": "https://www.virustotal.com/api/v3" } ], "security": [ {} ], "paths": { "/collections": { "post": { "summary": "Create a new collection", "description": "", "operationId": "collections-create", "parameters": [ { "name": "x-apikey", "in": "header", "description": "Your API key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "description": "Collection object", "format": "json" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"data\": {\n \"attributes\": {\n \"name\": \"Test collection\",\n \"description\": \"This is how to create a new collection via API.\",\n \"top_icon_md5\": [\n \"1bc1faf71106e964e44cb17ab4dd8d11\"\n ],\n \"tags\": [],\n \"ip_addresses_count\": 0,\n \"domains_count\": 1,\n \"creation_date\": 1614784765,\n \"last_modification_date\": 1614784765,\n \"references_count\": 0,\n \"alt_names\": [],\n \"urls_count\": 0,\n \"autogenerated_tags\": [],\n \"files_count\": 0\n },\n \"type\": \"collection\",\n \"id\": \"\",\n \"links\": {\n \"self\": \"https://www.virustotal.com/api/v3/collections/\"\n }\n }\n}" } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "example": "Test collection" }, "description": { "type": "string", "example": "This is how to create a new collection via API." }, "top_icon_md5": { "type": "array", "items": { "type": "string", "example": "1bc1faf71106e964e44cb17ab4dd8d11" } }, "tags": { "type": "array", "items": { "type": "object", "properties": {} } }, "ip_addresses_count": { "type": "integer", "example": 0, "default": 0 }, "domains_count": { "type": "integer", "example": 1, "default": 0 }, "creation_date": { "type": "integer", "example": 1614784765, "default": 0 }, "last_modification_date": { "type": "integer", "example": 1614784765, "default": 0 }, "references_count": { "type": "integer", "example": 0, "default": 0 }, "alt_names": { "type": "array", "items": { "type": "object", "properties": {} } }, "urls_count": { "type": "integer", "example": 0, "default": 0 }, "autogenerated_tags": { "type": "array", "items": { "type": "object", "properties": {} } }, "files_count": { "type": "integer", "example": 0, "default": 0 } } }, "type": { "type": "string", "example": "collection" }, "id": { "type": "string", "example": "" }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://www.virustotal.com/api/v3/collections/" } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false, "security": [], "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --request POST \\\n --url https://www.virustotal.com/api/v3/collections \\\n --header 'Content-Type: application/json' \\\n --header 'x-apikey: ' \\\n --data '{\n\t\"data\": {\n\t\t\"attributes\": {\n\t\t\t\"name\": \"Test collection\",\n\t\t\t\"description\": \"This is how to create a new collection via API.\"\n\t\t},\n\t\t\"relationships\": {\n\t\t\t\"domains\": {\n\t\t\t\t\"data\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"domain\",\n\t\t\t\t\t\t\"id\": \"www.virustotal.com\"\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"domain\",\n\t\t\t\t\t\t\"id\": \"www.hooli.com\"\n\t\t\t\t\t}\n\t\t\t\t]\n\t\t\t},\n\t\t\t\"urls\": {\n\t\t\t\t\"data\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"url\",\n\t\t\t\t\t\t\"url\": \"https://www.virustotal.com/\"\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"url\",\n\t\t\t\t\t\t\"id\": \"f11f7cc900638fae209f68498a90158fbfb067fc4191549ddb657e39cc4428c2\"\n\t\t\t\t\t}\n\t\t\t\t]\n\t\t\t},\n\t\t\t\"ip_addresses\": {\n\t\t\t\t\"data\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"ip_address\",\n\t\t\t\t\t\t\"id\": \"8.8.8.8\"\n\t\t\t\t\t}\n\t\t\t\t]\n\t\t\t},\n\t\t\t\"files\": {\n\t\t\t\t\"data\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"file\",\n\t\t\t\t\t\t\"id\": \"ecc0f2aa29b102bf8d67b7d7173e8698c0341ddfdf9757be17595460fbf1791a\"\n\t\t\t\t\t}\n\t\t\t\t]\n\t\t\t}\n\t\t},\n\t\t\"type\": \"collection\"\n\t}\n}'", "name": "Create collection from a JSON" }, { "language": "curl", "code": "curl --request POST \\\n --url https://www.virustotal.com/api/v3/collections \\\n --header 'Content-Type: application/json' \\\n --header 'x-apikey: ' \\\n --data '{\n\t\"data\": {\n\t\t\"attributes\": {\n\t\t\t\"name\": \"Test collection\",\n\t\t\t\"description\": \"This is how to create a new collection via API.\"\n\t\t},\n\t\t\"raw_items\": \"This is a text containing an IoC, www.virustotal.com\",\n\t\t\"type\": \"collection\"\n\t}\n}'", "name": "Create collection from a raw text" } ], "samples-languages": [ "curl" ] } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": false }, "x-readme-fauxas": true } ```