Create, Get, Update, Delete

Manage your concepts

Within your app, you can create concepts, modify them after creation, or get them from your app.

caution

We currently do not support deleting concepts since they have 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 and a large knowledge graph we've assembled over the years.

Create

Add Concepts

To create a new concept in your app, you POST the concept with an id and name. You can also post more than one concept in the same request by sending a list of concepts.

Below is an example of how to add concepts.

info

The initialization code used in the following examples is outlined in detail on the client installation page.

################################################################################
# In this section, we set the user authentication, app ID, concept ID and name.
# Change these strings to run your own example.
################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to whatever concepts you want to process
CONCEPT_ID = 'cat'
CONCEPT_NAME = 'Cat Name'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

post_concepts_response = stub.PostConcepts(
    service_pb2.PostConceptsRequest(
        user_app_id=userDataObject,
        concepts=[resources_pb2.Concept(id=CONCEPT_ID, name=CONCEPT_NAME)]
    ),
    metadata=metadata
)

if post_concepts_response.status.code != status_code_pb2.SUCCESS:
    print(post_concepts_response.status)
    raise Exception("Post concept failed, status: " + post_concepts_response.status.description)
    
print(post_concepts_response)

<!--index.html file-->

<script>
    ////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, concept ID and name.
    // Change these strings to run your own example.
    ////////////////////////////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    // Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';
    // Change these to whatever concepts you want to process
    const CONCEPT_ID = 'cat';
    const CONCEPT_NAME = 'Cat Name';

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const raw = JSON.stringify({
        "user_app_id": {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        "concepts": [
            {
                "id": CONCEPT_ID,
                "name": CONCEPT_NAME
            }
        ]
    });

    const requestOptions = {
        method: 'POST',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
        body: raw
    };

    fetch("https://api.clarifai.com/v2/concepts", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));
</script>

//index.js file

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept ID and name.
// Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to whatever concepts you want to process
const CONCEPT_ID = 'cat';
const CONCEPT_NAME = 'Cat Name';

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.PostConcepts(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        concepts: [{ id: CONCEPT_ID, name: CONCEPT_NAME }]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

        if (response.status.code !== 10000) {
            throw new Error("Post concepts failed, status: " + response.status.description);
        }
    }
);

package com.clarifai.example;

import com.clarifai.grpc.api.*;
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.status.StatusCode;

public class ClarifaiExample {

    ///////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, concept ID and name.
    // Change these strings to run your own example.
    ///////////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change these to whatever concepts you want to process
    static final String CONCEPT_ID = "charlie";
    static final String CONCEPT_NAME = "Charlie Name";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////	

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));

        MultiConceptResponse postConceptsResponse = stub.postConcepts(
            PostConceptsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .addConcepts(Concept.newBuilder().setId(CONCEPT_ID).setName(CONCEPT_NAME))
            .build()
        );

        if (postConceptsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Post concepts failed, status: " + postConceptsResponse.getStatus());
        }

    }

}

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept ID and name.
// Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change these to whatever concepts you want to process
$CONCEPT_ID = "cat";
$CONCEPT_NAME = "Cat Name";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\Api\Concept;
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostConceptsRequest;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->PostConcepts(
        // The request object carries the request along with the request status and other metadata related to the request itself
        new PostConceptsRequest([
            "user_app_id" => $userDataObject,
            "concepts" => [
                new Concept([
                    "id" => $CONCEPT_ID,
                    "name" => $CONCEPT_NAME
                ])
            ]         
        ]),
        $metadata
    )->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

print $response->serializeToJsonString();

?>

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/concepts" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "concepts": [
      {
        "id": "CONCEPT_ID_HERE",
        "name": "CONCEPT_NAME_HERE"
      }
      ]
  }'

Raw Output Example

status {
    code: SUCCESS
    description: "Ok"
    req_id: "9852fce206578f4bc5b6bed38f03eed8"
  }
  concepts {
    id: "cat"
    name: "Cat Name"
    value: 1.0
    created_at {
      seconds: 1643890626
      nanos: 775078265
    }
    language: "en"
    app_id: "a39423543bb941bf9ba2ee95fad11f0a"
    visibility {
      gettable: PRIVATE
    }
    user_id: "ei2l2oz3s3iz"
  }

Get

Get Concept by ID

Below is an example of how to get a single concept by its ID.

###########################################################################
# In this section, we set the user authentication, app ID, and concept ID.
# Change these strings to run your own example.
###########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change this to whatever concept you want to retrieve
CONCEPT_ID = 'cat'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

get_concepts_response = stub.GetConcept(
    service_pb2.GetConceptRequest(
        user_app_id=userDataObject,
        concept_id=CONCEPT_ID
    ),
    metadata=metadata
)

if get_concepts_response.status.code != status_code_pb2.SUCCESS:
    print(get_concepts_response.status)
    raise Exception("Get concept failed, status: " + get_concepts_response.status.description)
    
print(get_concepts_response)

<!--index.html file-->

<script>
    ////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and concept ID.
    // Change these strings to run your own example.
    ////////////////////////////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    //Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';
    // Change these to whatever concepts you want to process
    const CONCEPT_ID = 'cat';

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const requestOptions = {
        method: 'GET',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
    };

    fetch("https://api.clarifai.com/v2/users/" + USER_ID + "/apps/" + APP_ID + "/concepts/" + CONCEPT_ID, requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));
</script>

//index.js file

///////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and concept ID.
// Change these strings to run your own example.
///////////////////////////////////////////////////////////////////////////////

const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to whatever concepts you want to process
const CONCEPT_ID = 'cat';

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.GetConcept(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        concept_id: CONCEPT_ID
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

        if (response.status.code !== 10000) {
            throw new Error("Get concepts failed, status: " + response.status.description);
        }

        const concept = response.concept;
        console.log(JSON.stringify(concept, null, 2));
    }
);

package com.clarifai.example;

import com.clarifai.grpc.api.*;
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.status.StatusCode;

public class ClarifaiExample {

    ///////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and concept ID.
    // Change these strings to run your own example.
    ///////////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change this to whatever concept you want to retrieve
    static final String CONCEPT_ID = "charlie";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////	

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));

        SingleConceptResponse getConceptResponse = stub.getConcept(
            GetConceptRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .setConceptId(CONCEPT_ID)
            .build()
        );

        if (getConceptResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Get concepts failed, status: " + getConceptResponse.getStatus());
        }

        Concept concept = getConceptResponse.getConcept();
        System.out.println(concept);

    }

}

<?php

require __DIR__ . "/vendor/autoload.php";

///////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and concept ID.
// Change these strings to run your own example.
///////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change this to whatever concept you want to retrieve
$CONCEPT_ID = "cat";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\GetConceptRequest;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->GetConcept(
        // The request object carries the request along with the request status and other metadata related to the request itself
        new GetConceptRequest([
            "user_app_id" => $userDataObject,
            "concept_id"  => $CONCEPT_ID      
        ]),
        $metadata
    )->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

print $response->serializeToJsonString();

?>

curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/concepts/CONCEPT_ID_HERE" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  

Raw Output Example

status {
    code: SUCCESS
    description: "Ok"
    req_id: "240b8fa082722b0f137c09ec5141cfa3"
  }
  concept {
    id: "cat"
    name: "Cat Name"
    value: 1.0
    created_at {
      seconds: 1643890626
      nanos: 775078000
    }
    language: "en"
    app_id: "a39423543bb941bf9ba2ee95fad11f0a"
    visibility {
      gettable: PRIVATE
    }
    user_id: "ei2l2oz3s3iz"
  }

List Concepts

You can get a list of concepts within your app with a GET call. This call supports pagination.

Below is an example of how to list concepts.

###########################################################################
# In this section, we set the user authentication. 
# Change these strings to run your own example.
###########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_concepts_response = stub.ListConcepts(
    service_pb2.ListConceptsRequest(user_app_id=userDataObject),    
    metadata=metadata
)

if list_concepts_response.status.code != status_code_pb2.SUCCESS:
    print(list_concepts_response.status)
    raise Exception("List concept failed, status: " + list_concepts_response.status.description)
    
print(list_concepts_response)

<!--index.html file-->

<script>
    ////////////////////////////////////////////////////////////
    // In this section, we set the user authentication. 
    // Change these strings to run your own example.
    ////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    //Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const requestOptions = {
        method: 'GET',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
    };

    fetch("https://api.clarifai.com/v2/users/" + USER_ID + "/apps/" + APP_ID + "/concepts", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));
</script>

//index.js file

////////////////////////////////////////////////////////
// In this section, we set the user authentication. 
// Change these strings to run your own example.
////////////////////////////////////////////////////////

const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.ListConcepts(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

        if (response.status.code !== 10000) {
            throw new Error("List concepts failed, status: " + response.status.description);
        }
        for (const concepts of response.concepts) {
            console.log(concepts)
        }
    }
);

package com.clarifai.example;

import com.clarifai.grpc.api.*;
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.status.StatusCode;

public class ClarifaiExample {

    ///////////////////////////////////////////////////////////
    // In this section, we set the user authentication. 
    // Change these strings to run your own example.
    ///////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////	

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));

        MultiConceptResponse listConceptsResponse = stub.listConcepts(
            ListConceptsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .build()
        );

        if (listConceptsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("List concepts failed, status: " + listConceptsResponse.getStatus());
        }

        for (Concept concept: listConceptsResponse.getConceptsList()) {
            System.out.println(concept);
        }

    }

}

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////
// In this section, we set the user authentication. 
// Change these strings to run your own example.
////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\ListConceptsRequest;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->ListConcepts(
        // The request object carries the request along with the request status and other metadata related to the request itself
        new ListConceptsRequest([
            "user_app_id" => $userDataObject 
        ]),
        $metadata
    )->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

print $response->serializeToJsonString();

?>

curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/concepts" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
 

Raw Output Example

status {
    code: SUCCESS
    description: "Ok"
    req_id: "1155d18c386559cfdaa22274a0531d9f"
  }
  concepts {
    id: "cat"
    name: "Cat Name"
    value: 1.0
    created_at {
      seconds: 1643890626
      nanos: 775078000
    }
    language: "en"
    app_id: "a39423543bb941bf9ba2ee95fad11f0a"
    visibility {
      gettable: PRIVATE
    }
    user_id: "ei2leoz3s3iy"
  }
  concepts {
    id: "charlie"
    name: "Charlie Name"
    value: 1.0
    created_at {
      seconds: 1643865054
      nanos: 92351000
    }
    language: "en"
    app_id: "a39423543bb941bf9ba2ee95fad11f0a"
    visibility {
      gettable: PRIVATE
    }
    user_id: "ei2l2oz3s3iz"
  }

List Model Concepts

You can get a list of concepts within your model with a GET call. This call supports pagination.

Below is an example of how to list the concepts in your model.

note

If you are using any of the Clarifai gRPC clients, the ListModelConcepts endpoint, which lists concepts in a model, is only available from release 8.10.0.

Python
JavaScript (REST)
PHP
cURL

###########################################################################
# In this section, we set the user authentication and model ID.
# Change these strings to run your own example.
###########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change this to whatever model you want to retrieve its concepts
MODEL_ID = 'YOUR_MODEL_ID_HERE'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_model_concepts_response = stub.ListModelConcepts(
    service_pb2.ListModelConceptsRequest(
        user_app_id=userDataObject, 
        model_id=MODEL_ID
    ),    
    metadata=metadata
)

if list_model_concepts_response.status.code != status_code_pb2.SUCCESS:
    print(list_model_concepts_response.status)
    raise Exception("List model concept failed, status: " + list_model_concepts_response.status.description)
    
print(list_model_concepts_response)

<!--index.html file-->

<script>
    ///////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication and model ID.
    // Change these strings to run your own example.
    //////////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    //Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';
    // Change this to whatever model you want to retrieve its concepts
    const MODEL_ID = 'YOUR_MODEL_ID_HERE';

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const requestOptions = {
        method: 'GET',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
    };

    fetch("https://api.clarifai.com/v2/users/" + USER_ID + "/apps/" + APP_ID + "/models/" + MODEL_ID + "/concepts", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));
</script>

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////
// In this section, we set the user authentication. 
// Change these strings to run your own example.
////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change this to whatever model you want to retrieve its concepts
$MODEL_ID = "YOUR_MODEL_ID_HERE";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\ListModelConceptsRequest;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->ListModelConcepts(
        // The request object carries the request along with the request status and other metadata related to the request itself
        new ListModelConceptsRequest([
            "user_app_id" => $userDataObject,
            "model_id"  => $MODEL_ID
        ]),
        $metadata
    )->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

print $response->serializeToJsonString();

?>

curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/models/YOUR_MODEL_ID_HERE/concepts" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
 

Update

Update Concept Name

Below is an example of 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.

################################################################################
# In this section, we set the user authentication, app ID, concept ID and name.
# Change these strings to run your own example.
################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to whatever concept you want to update
CONCEPT_ID = 'cat'
CONCEPT_NAME = 'New Cat Name'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

patch_concepts_response = stub.PatchConcepts(
    service_pb2.PatchConceptsRequest(
        user_app_id=userDataObject,
        action="overwrite",  # The only supported action right now is overwrite
        concepts=[resources_pb2.Concept(id=CONCEPT_ID, name=CONCEPT_NAME)]
    ),
    metadata=metadata
)

if patch_concepts_response.status.code != status_code_pb2.SUCCESS:
    print(patch_concepts_response.status)
    raise Exception("Patch concept failed, status: " + patch_concepts_response.status.description)
    
print(patch_concepts_response)

<!--index.html file-->

<script>
    ////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, concept ID and name.
    // Change these strings to run your own example.
    ////////////////////////////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    // Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';
    // Change these to whatever concepts you want to update
    const CONCEPT_ID = 'cat';
    const CONCEPT_NAME = 'New Cat Name';

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const raw = JSON.stringify({
        "user_app_id": {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        "concepts": [
            {
                "id": CONCEPT_ID,
                "name": CONCEPT_NAME
            }
        ],
        "action": "overwrite"
    });

    const requestOptions = {
        method: 'PATCH',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
        body: raw
    };

    fetch("https://api.clarifai.com/v2/concepts", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));
</script>

//index.js file

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept ID and name.
// Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to whatever concepts you want to update
const CONCEPT_ID = 'cat';
const CONCEPT_NAME = 'New Cat Name';

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.PatchConcepts(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        action: "overwrite",  // The only supported action right now is overwrite
        concepts: [{ id: CONCEPT_ID, name: CONCEPT_NAME }]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

        if (response.status.code !== 10000) {
            throw new Error("Patch concepts failed, status: " + response.status.description);
        }
    }
);

package com.clarifai.example;

import com.clarifai.grpc.api.*;
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.status.StatusCode;

public class ClarifaiExample {

    ///////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, concept ID and name.
    // Change these strings to run your own example.
    //////////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change these to whatever concept you want to update
    static final String CONCEPT_ID = "cat";
    static final String CONCEPT_NAME = "New Cat Name";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////	

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));

        MultiConceptResponse patchConceptsResponse = stub.patchConcepts(
            PatchConceptsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .setAction("overwrite") // The only supported action right now is overwrite
            .addConcepts(Concept.newBuilder().setId(CONCEPT_ID).setName(CONCEPT_NAME))
            .build()
        );

        if (patchConceptsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Patch concepts failed, status: " + patchConceptsResponse.getStatus());
        }

    }

}

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept ID and name.
// Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change these to whatever concepts you want to update
$CONCEPT_ID = "cat";
$CONCEPT_NAME = "New Cat Name";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\Api\Concept;
use Clarifai\ClarifaiClient;
use Clarifai\Api\PatchConceptsRequest;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->PatchConcepts(
        // The request object carries the request along with the request status and other metadata related to the request itself
        new PatchConceptsRequest([
            "user_app_id" => $userDataObject,
            "action"  => "overwrite",
            "concepts" => [
                new Concept([
                    "id" => $CONCEPT_ID,
                    "name" => $CONCEPT_NAME
                ])
            ]
        ]),
        $metadata
    )->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

print $response->serializeToJsonString();

?>

curl -X PATCH "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/concepts" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "concepts": [
      {
        "id": "cat",
        "name": "New Cat Name"
      }
      ],
    "action": "overwrite"
  }' 

Raw Output Example

status {
    code: SUCCESS
    description: "Ok"
    req_id: "67ba891f905e081690e4e94522fc21c7"
  }
  concepts {
    id: "cat"
    name: "New Cat Name"
    value: 1.0
    created_at {
      seconds: 1643897414
      nanos: 497920914
    }
    language: "en"
    app_id: "a39423543bb941bf9ba2ee95fad11f0a"
    user_id: "ei2l2oz3s3iz"
  }

Create, Get, Update, Delete

Create​

Add Concepts​

Get​

Get Concept by ID​

List Concepts​

List Model Concepts​

Update​

Update Concept Name​

What did you think of this doc?

Create

Add Concepts

Get

Get Concept by ID

List Concepts

List Model Concepts

Update

Update Concept Name