# Create a tag

- Operation ID: `createTagUsingPOST`
- HTTP method: `POST`
- Path: `/v4/tags`
- [Human-readable API reference](https://hub.synerise.com/api-reference/asset-management#operation/createTagUsingPOST)

## Self-contained OpenAPI method

The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.

```yaml
openapi: 3.0.0
info:
  title: Synerise Public API
  version: 1.9.5
paths:
  /v4/tags:
    post:
      tags:
        - Tags
      summary: Create a tag
      description: |
        Create a new tag that can be assigned to profiles. If you try to create a tag that already exists, the response is the existing tag.

        ---

        **API consumers:** <a href="/api-reference/authorization?tag=Authorization&amp;operationId=profileLogin" target="_blank" rel="noopener">Workspace (Business Profile)</a>, <a href="/api-reference/authorization?tag=Authorization&amp;operationId=userLogin" target="_blank" rel="noopener">Synerise User</a>

        **API key permission required:** `API_TAGS_CREATE`

        **User role permission required:** `client_tags: create`
      operationId: createTagUsingPOST
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  description: Name of the tag
                  type: string
                  example: nice tag
                color:
                  description: Display color of the tag; hexadecimal value
                  type: string
                  example: "#0768ff"
      responses:
        "200":
          description: Tag created
          content:
            application/json:
              schema:
                type: object
                properties:
                  businessProfileId:
                    type: integer
                    description: ID of the Workspace where the tag was created
                    example: 100005
                  id:
                    description: ID of the tag
                    type: integer
                    format: int32
                    example: 645
                  name:
                    description: Name of the tag
                    type: string
                    example: nice tag
                  color:
                    description: Display color of the tag; hexadecimal value
                    type: string
                    example: "#0768ff"
        "400":
          description: Invalid or incomplete data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Summary of the error
                  status:
                    type: integer
                    format: int32
                    description: Status code
                  timestamp:
                    type: string
                    description: Time when the message was sent
                  path:
                    type: string
                    description: URL of the requested resource
                  message:
                    type: string
                    description: Description of the problem
                  errors:
                    type: array
                    description: Additional details of the errors, if applicable
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                          format: int32
                          example: 12082
                          description: A numeric identifier of the error type
                        field:
                          type: string
                          example: countryCode
                          description: Field in the request body that caused the error
                        message:
                          type: string
                          example: Country Code must have 0 or 3 characters as per ISO format.
                          description: A detailed description of the problem
                        rejectedValue:
                          type: string
                          example: Poland
                          description: The value that caused the error
              example:
                error: Bad Request
                status: 400
                timestamp: 2020-10-29T11:02:25.939Z
                path: /tags
                message: Some fields did not pass validation
                errors:
                  - code: 16213
                    field: name
                    message: Scripts are not allowed
        "401":
          description: "Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc."
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Summary of the error
                  status:
                    type: integer
                    format: int32
                    description: Status code
                  timestamp:
                    type: string
                    description: Time when the message was sent
                  path:
                    type: string
                    description: URL of the requested resource
                  message:
                    type: string
                    description: Description of the problem
                  errors:
                    type: array
                    description: Additional details of the errors, if applicable
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                          format: int32
                          example: 12082
                          description: A numeric identifier of the error type
                        field:
                          type: string
                          example: countryCode
                          description: Field in the request body that caused the error
                        message:
                          type: string
                          example: Country Code must have 0 or 3 characters as per ISO format.
                          description: A detailed description of the problem
                        rejectedValue:
                          type: string
                          example: Poland
                          description: The value that caused the error
              example:
                error: Bad Request
                status: 400
                timestamp: 2020-10-29T13:08:16.235Z
                path: /exampleEndpoint
                message: Some fields did not pass validation
                errors:
                  - code: 120
                    field: exampleField
                    message: "120"
                    rejectedValue: exampleValue
        "403":
          description: Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Summary of the error
                  status:
                    type: integer
                    format: int32
                    description: Status code
                  timestamp:
                    type: string
                    description: Time when the message was sent
                  path:
                    type: string
                    description: URL of the requested resource
                  message:
                    type: string
                    description: Description of the problem
                  errors:
                    type: array
                    description: Additional details of the errors, if applicable
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                          format: int32
                          example: 12082
                          description: A numeric identifier of the error type
                        field:
                          type: string
                          example: countryCode
                          description: Field in the request body that caused the error
                        message:
                          type: string
                          example: Country Code must have 0 or 3 characters as per ISO format.
                          description: A detailed description of the problem
                        rejectedValue:
                          type: string
                          example: Poland
                          description: The value that caused the error
              example:
                timestamp: 2018-06-07T07:29:27.489+00:00
                status: 403
                error: Forbidden
                message: Forbidden
                path: /path_of_the_endpoint
        "415":
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Summary of the error
                  status:
                    type: integer
                    format: int32
                    description: Status code
                  timestamp:
                    type: string
                    description: Time when the message was sent
                  path:
                    type: string
                    description: URL of the requested resource
                  message:
                    type: string
                    description: Description of the problem
                  errors:
                    type: array
                    description: Additional details of the errors, if applicable
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                          format: int32
                          example: 12082
                          description: A numeric identifier of the error type
                        field:
                          type: string
                          example: countryCode
                          description: Field in the request body that caused the error
                        message:
                          type: string
                          example: Country Code must have 0 or 3 characters as per ISO format.
                          description: A detailed description of the problem
                        rejectedValue:
                          type: string
                          example: Poland
                          description: The value that caused the error
              example:
                timestamp: 2018-06-07T07:27:23.136+00:00
                status: 415
                error: Unsupported Media Type
                message: Content type 'application/xml' not supported
                path: /path_of_the_endpoint
      security:
        - JWT: []
        - BasicAuth: []
      x-snr-doc-urls:
        - /api-reference/data-management#tag/Tags/operation/createTagUsingPOST
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl --request POST \
              --url https://api.synerise.com/v4/tags \
              --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
              --header 'content-type: application/json' \
              --data '{"name":"nice tag","color":"#0768ff"}'
        - lang: Python
          label: Python
          source: |-
            import http.client

            conn = http.client.HTTPSConnection("api.synerise.com")

            payload = "{\"name\":\"nice tag\",\"color\":\"#0768ff\"}"

            headers = {
                'Authorization': "Basic REPLACE_BASIC_AUTH",
                'content-type': "application/json"
                }

            conn.request("POST", "/v4/tags", payload, headers)

            res = conn.getresponse()
            data = res.read()

            print(data.decode("utf-8"))
        - lang: JavaScript
          label: JavaScript
          source: |-
            const data = JSON.stringify({
              "name": "nice tag",
              "color": "#0768ff"
            });

            const xhr = new XMLHttpRequest();
            xhr.withCredentials = true;

            xhr.addEventListener("readystatechange", function () {
              if (this.readyState === this.DONE) {
                console.log(this.responseText);
              }
            });

            xhr.open("POST", "https://api.synerise.com/v4/tags");
            xhr.setRequestHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
            xhr.setRequestHeader("content-type", "application/json");

            xhr.send(data);
        - lang: Node.js
          label: Node.js
          source: |-
            const http = require("https");

            const options = {
              "method": "POST",
              "hostname": "api.synerise.com",
              "port": null,
              "path": "/v4/tags",
              "headers": {
                "Authorization": "Basic REPLACE_BASIC_AUTH",
                "content-type": "application/json"
              }
            };

            const req = http.request(options, function (res) {
              const chunks = [];

              res.on("data", function (chunk) {
                chunks.push(chunk);
              });

              res.on("end", function () {
                const body = Buffer.concat(chunks);
                console.log(body.toString());
              });
            });

            req.write(JSON.stringify({name: 'nice tag', color: '#0768ff'}));
            req.end();
        - lang: PHP
          label: PHP
          source: |-
            <?php

            $request = new HttpRequest();
            $request->setUrl('https://api.synerise.com/v4/tags');
            $request->setMethod(HTTP_METH_POST);

            $request->setHeaders([
              'Authorization' => 'Basic REPLACE_BASIC_AUTH',
              'content-type' => 'application/json'
            ]);

            $request->setBody('{"name":"nice tag","color":"#0768ff"}');

            try {
              $response = $request->send();

              echo $response->getBody();
            } catch (HttpException $ex) {
              echo $ex;
            }
        - lang: Java
          label: Java
          source: |-
            HttpResponse<String> response = Unirest.post("https://api.synerise.com/v4/tags")
              .header("Authorization", "Basic REPLACE_BASIC_AUTH")
              .header("content-type", "application/json")
              .body("{\"name\":\"nice tag\",\"color\":\"#0768ff\"}")
              .asString();
servers:
  - url: https://api.synerise.com
    description: Microsoft Azure EU
  - url: https://api.azu.synerise.com
    description: Microsoft Azure USA
  - url: https://api.geb.synerise.com
    description: Google Cloud Platform
tags:
  - name: Tags
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      description: |
        Synerise uses [JSON Web Token (JWT)](https://jwt.io/) as the authorization method.

        The token is generated by the *auth/login* endpoints.

        You need to include it in the `Authorization` header of your requests, with a `Bearer` prefix.


        By default, the token is valid for **one week** (see [workspace settings](https://hub.synerise.com/docs/settings/tool/iam-for-apps/general/#jwt-lifetime)).  
        You can request a refreshed key for the session by using the *auth/refresh* endpoint **before** the current token expires.


        You can verify your JWT signature by using the [public key](https://api.synerise.com/v4/public.pem).


        See Developer Guides on JWT API authentication for:
        - [profiles](https://hub.synerise.com/developers/api/api-authorization/client-login/);
        - [workspaces](https://hub.synerise.com/developers/api/api-authorization/workspace-login/#api-authentication-with-jwt);
        - [users](https://hub.synerise.com/developers/api/api-authorization/user-login/).
    BasicAuth:
      type: http
      scheme: basic
      description: |
        Basic authentication with login (workspace GUID) and password (workspace API key) encoded with Base64 and sent in the `Authorization` header. **Must be enabled in the settings of the API key**.

        <span style="color:red">This is less secure than JWTs.</span> Limit the API key permissions to only those that you need. Consider API key rotation and other security measures.

        You can still use JWTs from the same API key when basic authentication is enabled.

        For details, see ["Workspace authentication"](https://hub.synerise.com/jwt-or-basic/#basic-api-authentication-with-api-keys).
```