Create a concept with user-defined ID

PUT

https://api.contentful.com/organizations/:organization_id/taxonomy/concepts/:concept_id

PUT

/organizations/:organization_id/taxonomy/concepts/:concept_id

$ curl -X PUT https://api.contentful.com/organizations/0D9ZC8rLWiw6x5qizZGiRs/taxonomy/concepts/3kZdDUXy9n0l2Xi2cq8TPc \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/vnd.contentful.management.v1+json" \
>      -d '{
>   "uri": "",
>   "prefLabel": {
>     "en-US": "Sofas"
>   },
>   "altLabels": {
>     "en-US": [
>       "Couches",
>       "Settees"
>     ]
>   },
>   "hiddenLabels": {
>     "en-US": [
>       "Davenports"
>     ]
>   },
>   "notations": [
>     "FURN0017B"
>   ],
>   "note": {
>     "en-US": ""
>   },
>   "changeNote": {
>     "en-US": ""
>   },
>   "definition": {
>     "en-US": ""
>   },
>   "editorialNote": {
>     "en-US": ""
>   },
>   "example": {
>     "en-US": ""
>   },
>   "historyNote": {
>     "en-US": ""
>   },
>   "scopeNote": {
>     "en-US": ""
>   },
>   "broader": [
>     {
>       "sys": {
>         "id": "1Py5SjffQHkGGY3dZ02W14"
>       }
>     }
>   ],
>   "related": [
>     {
>       "sys": {
>         "id": "5abcWINB018mASQ5Fdrkbj"
>       }
>     }
>   ]
> }'

201Taxonomy_createAConceptWithUserDefinedId_example

1 {
2   "sys": {
3     "id": "3kZdDUXy9n0l2Xi2cq8TPc",
4     "type": "TaxonomyConcept",
5     "organization": {
6       "sys": {
7         "id": "0D9ZC8rLWiw6x5qizZGiRs",
8         "type": "Link",
9         "linkType": "Organization"
10       }
11     },
12     "createdAt": "2026-02-21T13:05:27.000Z",
13     "createdBy": {
14       "sys": {
15         "type": "Link",
16         "linkType": "User",
17         "id": "7BslKh9TdKGOK41VmLDjFZ"
18       }
19     },
20     "updatedAt": "2026-02-21T13:05:27.000Z",
21     "updatedBy": {
22       "sys": {
23         "type": "Link",
24         "linkType": "User",
25         "id": "4FLrUHftHW3v2BLi9fzfjU"
26       }
27     },
28     "version": 0
29   },
30   "uri": "",
31   "prefLabel": {
32     "en-US": "Sofas"
33   },
34   "altLabels": {
35     "en-US": [
36       "Couches",
37       "Settees"
38     ]
39   },
40   "hiddenLabels": {
41     "en-US": [
42       "Davenports"
43     ]
44   },
45   "notations": [
46     "FURN0017B"
47   ],
48   "note": {
49     "en-US": ""
50   },
51   "changeNote": {
52     "en-US": ""
53   },
54   "definition": {
55     "en-US": ""
56   },
57   "editorialNote": {
58     "en-US": ""
59   },
60   "example": {
61     "en-US": ""
62   },
63   "historyNote": {
64     "en-US": ""
65   },
66   "scopeNote": {
67     "en-US": ""
68   },
69   "broader": [
70     {
71       "sys": {
72         "id": "1Py5SjffQHkGGY3dZ02W14",
73         "type": "Link",
74         "linkType": "TaxonomyConcept"
75       }
76     }
77   ],
78   "related": [
79     {
80       "sys": {
81         "id": "5abcWINB018mASQ5Fdrkbj",
82         "type": "Link",
83         "linkType": "TaxonomyConcept"
84       }
85     }
86   ],
87   "conceptSchemes": [
88     {
89       "sys": {
90         "type": "Link",
91         "linkType": "TaxonomyConceptScheme",
92         "id": "2s0F7127ajju1AVToMaCtE"
93       }
94     }
95   ]
96 }

Creates a single taxonomy concept with a user-defined ID.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

organization_idstringRequired

The ID of the organization.

concept_idstringRequired

The user-defined ID of the concept.

Request

This endpoint expects a map from strings to any.

Response headers

Content-Typestring

Content-Type

Response

Created - Resource created successfully