Create, Get, Update
Manage your concepts.
Within your app you can create concpets, modify them after creation an get them from yoru app. We currently do not support deleting concepts since they are such an integral tie across almost all other data structures in the platform like inputs, models, searches, etc.
You will find that some of our endpoints have additional information returned from the clarifai/main app which contains our pre-trained models but also a large knowledge graph we've assembled over the years.

Create

Add Concepts

To create a new concept in you app you POST the concept with an id and name. You can also post more than one concept in the same API by sending a list of concepts.
Java
NodeJS
Python
cURL
Javascript (REST)
1
import com.clarifai.grpc.api.*;
2
import com.clarifai.grpc.api.status.*;
3
4
// Insert here the initialization code as outlined on this page:
5
// https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
6
7
MultiConceptResponse postConceptsResponse = stub.postConcepts(
8
PostConceptsRequest.newBuilder()
9
.addConcepts(Concept.newBuilder().setId("charlie").setName("Charlie Name"))
10
.build()
11
);
12
13
if (postConceptsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
14
throw new RuntimeException("Post concepts failed, status: " + postConceptsResponse.getStatus());
15
}
Copied!
1
// Insert here the initialization code as outlined on this page:
2
// https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
3
4
stub.PostConcepts(
5
{
6
concepts: [{id: "charlie", name: "Charlie Name"}]
7
},
8
metadata,
9
(err, response) => {
10
if (err) {
11
throw new Error(err);
12
}
13
14
if (response.status.code !== 10000) {
15
throw new Error("Post concepts failed, status: " + response.status.description);
16
}
17
}
18
);
Copied!
1
# Insert here the initialization code as outlined on this page:
2
# https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
3
4
post_concepts_response = stub.PostConcepts(
5
service_pb2.PostConceptsRequest(
6
concepts=[resources_pb2.Concept(id="charlie", name="Charlie Name")]
7
),
8
metadata=metadata
9
)
10
11
if post_concepts_response.status.code != status_code_pb2.SUCCESS:
12
print("There was an error with your request!")
13
print("\tCode: {}".format(post_concepts_response.outputs[0].status.code))
14
print("\tDescription: {}".format(post_concepts_response.outputs[0].status.description))
15
print("\tDetails: {}".format(post_concepts_response.outputs[0].status.details))
16
raise Exception("Post concept failed, status: " + post_concepts_response.status.description)
Copied!
1
curl -X POST \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '
5
{
6
"concepts": [
7
{
8
"id": "{concept_id}",
9
"name": "{new_concept_name}"
10
}
11
]
12
}'\
13
https://api.clarifai.com/v2/concepts
Copied!
1
const raw = JSON.stringify({
2
"user_app_id": {
3
"user_id": "{YOUR_USER_ID}",
4
"app_id": "{YOUR_APP_ID}"
5
},
6
"concepts": [
7
{
8
"id": "{CONCEPT_ID}",
9
"name": "{CONCEPT_NAME}"
10
}
11
]
12
});
13
14
const requestOptions = {
15
method: 'POST',
16
headers: {
17
'Accept': 'application/json',
18
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
19
},
20
body: raw
21
};
22
23
fetch("https://api.clarifai.com/v2/concepts", requestOptions)
24
.then(response => response.text())
25
.then(result => console.log(result))
26
.catch(error => console.log('error', error));
Copied!

Get

Get Concept by ID

You can get a singular concept by it's ID.
Java
NodeJS
Python
cURL
Javascript (REST)
1
import com.clarifai.grpc.api.*;
2
import com.clarifai.grpc.api.status.*;
3
4
// Insert here the initialization code as outlined on this page:
5
// https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
6
7
SingleConceptResponse getConceptResponse = stub.getConcept(
8
GetConceptRequest.newBuilder()
9
.setConceptId("charlie")
10
.build()
11
);
12
13
if (getConceptsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
14
throw new RuntimeException("Get concepts failed, status: " + getConceptsResponse.getStatus());
15
}
Copied!
1
// Insert here the initialization code as outlined on this page:
2
// https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
3
4
stub.GetConcept(
5
{
6
concept_id: "bosco"
7
},
8
metadata,
9
(err, response) => {
10
if (err) {
11
throw new Error(err);
12
}
13
14
if (response.status.code !== 10000) {
15
throw new Error("Get concepts failed, status: " + response.status.description);
16
}
17
}
18
);
Copied!
1
# Insert here the initialization code as outlined on this page:
2
# https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
3
4
get_concepts_response = stub.GetConcept(
5
service_pb2.GetConceptRequest(
6
concept_id="charlie"
7
),
8
metadata=metadata
9
)
10
11
if get_concepts_response.status.code != status_code_pb2.SUCCESS:
12
print("There was an error with your request!")
13
print("\tCode: {}".format(get_concepts_response.outputs[0].status.code))
14
print("\tDescription: {}".format(get_concepts_response.outputs[0].status.description))
15
print("\tDetails: {}".format(get_concepts_response.outputs[0].status.details))
16
raise Exception("Get concept failed, status: " + get_concepts_response.status.description)
Copied!
1
curl -X GET \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
https://api.clarifai.com/v2/concepts/{concept_id}
Copied!
1
const conceptId = '{CONCEPT_ID}'
2
const appId = '{YOUR_APP_ID}'
3
4
const requestOptions = {
5
method: 'GET',
6
headers: {
7
'Accept': 'application/json',
8
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
9
}
10
};
11
12
fetch(`https://api.clarifai.com/v2/users/me/apps/${appId}/concepts/${conceptId}`, requestOptions)
13
.then(response => response.text())
14
.then(result => console.log(result))
15
.catch(error => console.log('error', error));
Copied!

List concepts

You can get a list of concepts within your app with a GET call. This call supports pagination
Java
NodeJS
Python
cURL
Javascript (REST)
1
import com.clarifai.grpc.api.*;
2
import com.clarifai.grpc.api.status.*;
3
4
// Insert here the initialization code as outlined on this page:
5
// https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
6
7
MultiConceptResponse listConceptsResponse = stub.listConcepts(
8
ListConceptsRequest.newBuilder()
9
.build()
10
);
11
12
if (listConceptsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
13
throw new RuntimeException("List concepts failed, status: " + listConceptsResponse.getStatus());
14
}
Copied!
1
// Insert here the initialization code as outlined on this page:
2
// https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
3
4
stub.ListConcepts(
5
{},
6
metadata,
7
(err, response) => {
8
if (err) {
9
throw new Error(err);
10
}
11
12
if (response.status.code !== 10000) {
13
throw new Error("List concepts failed, status: " + response.status.description);
14
}
15
}
16
);
Copied!
1
# Insert here the initialization code as outlined on this page:
2
# https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
3
4
list_concepts_response = stub.ListConcepts(
5
service_pb2.ListConceptsRequest(),
6
metadata=metadata
7
)
8
9
if list_concepts_response.status.code != status_code_pb2.SUCCESS:
10
print("There was an error with your request!")
11
print("\tCode: {}".format(list_concepts_response.outputs[0].status.code))
12
print("\tDescription: {}".format(list_concepts_response.outputs[0].status.description))
13
print("\tDetails: {}".format(list_concepts_response.outputs[0].status.details))
14
raise Exception("List concept failed, status: " + list_concepts_response.status.description)
Copied!
1
curl -X GET \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
https://api.clarifai.com/v2/concepts
Copied!
1
const appId = '{YOUR_APP_ID}'
2
3
const requestOptions = {
4
method: 'GET',
5
headers: {
6
'Accept': 'application/json',
7
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
8
}
9
};
10
11
fetch(`https://api.clarifai.com/v2/users/me/apps/${appId}/concepts`, requestOptions)
12
.then(response => response.text())
13
.then(result => console.log(result))
14
.catch(error => console.log('error', error));
Copied!

Update

Update Concept Name

The code below showcases how to update a concept's name given its id by using the "overwrite" action. You can also patch multiple concepts by sending a list of concepts.
Java
NodeJS
Python
cURL
Javascript (REST)
1
import com.clarifai.grpc.api.*;
2
import com.clarifai.grpc.api.status.*;
3
4
// Insert here the initialization code as outlined on this page:
5
// https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
6
7
MultiConceptResponse patchConceptsResponse = stub.patchConcepts(
8
PatchConceptsRequest.newBuilder()
9
.setAction("overwrite") // The only supported action right now is overwrite.
10
.addConcepts(Concept.newBuilder().setId("charlie").setName("Charlie Name"))
11
.build()
12
);
13
14
if (patchConceptsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
15
throw new RuntimeException("Patch concepts failed, status: " + patchConceptsResponse.getStatus());
16
}
Copied!
1
// Insert here the initialization code as outlined on this page:
2
// https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
3
4
stub.PatchConcepts(
5
{
6
action: "overwrite", // The only supported action right now is overwrite
7
concepts: [{id: "charlie", name: "Charlie Name"}]
8
},
9
metadata,
10
(err, response) => {
11
if (err) {
12
throw new Error(err);
13
}
14
15
if (response.status.code !== 10000) {
16
throw new Error("Patch concepts failed, status: " + response.status.description);
17
}
18
}
19
);
Copied!
1
# Insert here the initialization code as outlined on this page:
2
# https://docs.clarifai.com/api-guide/api-overview/api-clients#client-installation-instructions
3
4
patch_concepts_response = stub.PatchConcepts(
5
service_pb2.PatchConceptsRequest(
6
action="overwrite", # The only supported action right now is overwrite.
7
concepts=[resources_pb2.Concept(id="charlie", name="Charlie Name")]
8
),
9
metadata=metadata
10
)
11
12
if patch_concepts_response.status.code != status_code_pb2.SUCCESS:
13
print("There was an error with your request!")
14
print("\tCode: {}".format(patch_concepts_response.outputs[0].status.code))
15
print("\tDescription: {}".format(patch_concepts_response.outputs[0].status.description))
16
print("\tDetails: {}".format(patch_concepts_response.outputs[0].status.details))
17
raise Exception("Patch concept failed, status: " + patch_concepts_response.status.description)
Copied!
1
curl -X PATCH \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '
5
{
6
"concepts": [
7
{
8
"id": "charlie",
9
"name": "Charlie Name"
10
}
11
],
12
"action": "overwrite"
13
}'\
14
https://api.clarifai.com/v2/concepts
Copied!
1
const raw = JSON.stringify({
2
"user_app_id": {
3
"user_id": "{YOUR_USER_ID}",
4
"app_id": "{YOUR_APP_ID}"
5
},
6
"concepts": [
7
{
8
"id": "charlie",
9
"name": "Charlie Name"
10
}
11
],
12
"action": "overwrite"
13
});
14
15
const requestOptions = {
16
method: 'PATCH',
17
headers: {
18
'Accept': 'application/json',
19
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
20
},
21
body: raw
22
};
23
24
fetch("https://api.clarifai.com/v2/concepts", requestOptions)
25
.then(response => response.text())
26
.then(result => console.log(result))
27
.catch(error => console.log('error', error));
Copied!
Last modified 1mo ago