Update Annotations

Changing annotation data is possible by PATCHing existing annotations. The application owner can change any user-created annotations. Collaborators are not allowed to change annotations made by other collaborators.

Generally speaking, you should send PATCH when you want to change the data you have posted; for example, changing the concept from positive to negative or adjusting the bounding box coordinates.

If you want to add more tags, you can always POST new annotations. There is no limit on how many annotations an input can have.

Update supports overwrite, merge, and remove actions. You can update from 1 up to 128 annotations in a single API call.

Update Annotation With Concepts

Below is an example of how to update an annotation of an image with a new concept, or change a concept value from true to false (or vice versa).

Python (gRPC)

####################################################################################
# In this section, we set the user authentication, app ID, input ID, annotation 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 these based on the annotation you want to update
INPUT_ID = '53d0362a9dfa4e03b2293375e2d0db73'
ANNOTATION_ID = '300b8e39a65e4f33ae4e15e86eaf4a3b'
CONCEPT_ID = 'apple'

##########################################################################
# 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_annotations_response = stub.PatchAnnotations(
    service_pb2.PatchAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        action="merge",  # Supported actions: overwrite, merge, remove.
        annotations=[
            resources_pb2.Annotation(
                input_id=INPUT_ID,
                id=ANNOTATION_ID,
                data=resources_pb2.Data(
                    concepts=[
                        resources_pb2.Concept(id=CONCEPT_ID, value=1.)  # 1 means true, this concept is present.
                    ]
                )
            )
        ]
    ),
    metadata=metadata
)

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

JavaScript (REST)

<!--index.html file-->

<script>
    //////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, input ID, annotation 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 based on the annotation you want to update
    const INPUT_ID = 'c9cbb1c90cf24bc98bfd2e529e744ca9';
    const ANNOTATION_ID = '08d3b9b81432477fb5522d3fb1d1a6f4';
    const CONCEPT_ID = 'apple';

    ///////////////////////////////////////////////////////////////////////////////////
    // 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
        },
        "annotations": [
            {
                "input_id": INPUT_ID,
                "id": ANNOTATION_ID,
                "data": {
                    "concepts": [
                        {
                            "id": CONCEPT_ID,
                            "value": 1
                        }
                    ]
                }
            }
        ],
        "action": "merge"
    });

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

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

Node.js (gRPC)

//index.js file

//////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, input ID, annotation 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 based on the annotation you want to update
const INPUT_ID = 'c9cbb1c90cf24bc98bfd2e529e744ca9';
const ANNOTATION_ID = '08d3b9b81432477fb5522d3fb1d1a6f4';
const CONCEPT_ID = 'apple';

/////////////////////////////////////////////////////////////////////////////
// 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.PatchAnnotations(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        action: "merge",  // Supported actions: overwrite, merge, remove.
        annotations: [
            {
                input_id: INPUT_ID,
                id: ANNOTATION_ID,
                // 1 means true, this concept is present.
                // 0 means false, this concept is not present.
                data: {
                    concepts: [
                        { id: CONCEPT_ID, value: 1 }
                    ]
                }
            }
        ]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

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

Java (gRPC)

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, input ID, annotation 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 these based on the annotation you want to update
    static final String INPUT_ID = "c9cbb1c90cf24bc98bfd2e529e744ca9";
    static final String ANNOTATION_ID = "08d3b9b81432477fb5522d3fb1d1a6f4";
    static final String CONCEPT_ID = "apple";

    ///////////////////////////////////////////////////////////////////////////////////
    // 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));

        MultiAnnotationResponse patchAnnotationsResponse = stub.patchAnnotations(
            PatchAnnotationsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .setAction("merge") // Supported actions: overwrite, merge, remove
            .addAnnotations(
                Annotation.newBuilder()
                .setInputId(INPUT_ID)
                .setId(ANNOTATION_ID)
                .setData(
                    Data.newBuilder().addConcepts(
                        Concept.newBuilder()
                        .setId(CONCEPT_ID)
                        .setValue(1f) // 1 means true, this concept is present
                        .build()
                    )
                )
                .build()
            ).build()
        );

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

    }

}

PHP (gRPC)

<?php

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

//////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, input ID, annotation 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 these based on the annotation you want to update
$INPUT_ID = "c9cbb1c90cf24bc98bfd2e529e744ca9";
$ANNOTATION_ID = "08d3b9b81432477fb5522d3fb1d1a6f4";
$CONCEPT_ID = "apple";

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

use Clarifai\ClarifaiClient;
use Clarifai\Api\PatchAnnotationsRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
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->PatchAnnotations(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PatchAnnotationsRequest([
        "user_app_id" => $userDataObject, 
        "action" => "merge",  // Supported actions: overwrite, merge, remove
        "annotations" => [
             new Annotation([
                "input_id" => $INPUT_ID,
                "id" => $ANNOTATION_ID,
                "data" => new Data([
                    "concepts" => [
                        new Concept(["id" => $CONCEPT_ID, "value" => 1.]) //  1 means true, this concept is present
                    ]
                ])
             ])
        ]
    ]),
    $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());
}

?>

cURL

# Value of 1 means true, this concept is present
# Value of 0 means false, this concept is not present

curl -X PATCH "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "input_id": "YOUR_INPUT_ID_HERE",
        "id": "YOUR_ANNOTATION_ID_HERE",
        "data": {
          "concepts": [
            {
              "id": "apple",
              "value": 1
            }
          ]
        }
      }
    ],
    "action":"merge"
}'

Update Annotation With Concepts in a Region

When you update region data, you must nest this new data within region.data. Set the region_id to the current region_id if you do not want to change or remove this region.

Below is an example of how to update annotation with concepts in a region.

Python (gRPC)

####################################################################################
# In this section, we set the user authentication, app ID, input ID, annotation ID, 
# concept ID, and region 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 these based on the annotation you want to update
INPUT_ID = '53d0362a9dfa4e03b2293375e2d0db73'
ANNOTATION_ID = '300b8e39a65e4f33ae4e15e86eaf4a3b'
CONCEPT_ID = 'tree'
REGION_ID = '361d6a9253be9152968012660258a4bf'

##########################################################################
# 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_annotations_response = stub.PatchAnnotations(
    service_pb2.PatchAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        action="merge",  # Supported actions: overwrite, merge, remove.
        annotations=[
            resources_pb2.Annotation(
                input_id=INPUT_ID,
                id=ANNOTATION_ID,
                data=resources_pb2.Data(
                    regions=[
                        resources_pb2.Region(
                            id=REGION_ID,  # this should be the region id of this annotation before patch
                            data=resources_pb2.Data(
                                concepts=[
                                    resources_pb2.Concept(id=CONCEPT_ID, value=1.),  # 1 means true, this concept is present.
                                ]
                            )
                        )
                    ]
                )
            )
        ]
    ),
    metadata=metadata
)

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

JavaScript (REST)

<!--index.html file-->

<script>
    //////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, input ID, annotation ID, 
    // concept ID, and region 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 based on the annotation you want to update
    const INPUT_ID = 'c9cbb1c90cf24bc98bfd2e529e744ca9';
    const ANNOTATION_ID = '08d3b9b81432477fb5522d3fb1d1a6f4';
    const CONCEPT_ID = 'tree';
    const REGION_ID = '361d6a9253be9152968012660258a4bf';

    ///////////////////////////////////////////////////////////////////////////////////
    // 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
        },
        "annotations": [
            {
                "input_id": INPUT_ID,
                "id": ANNOTATION_ID,
                "data": {
                    "regions": [
                        {
                            "id": REGION_ID,
                            "data": {
                                "concepts": [
                                    {
                                        "id": CONCEPT_ID,
                                        "value": 1
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        ],
        "action": "merge"
    });

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

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

</script>

Node.js (gRPC)

//index.js file

//////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, input ID, annotation ID, 
// concept ID, and region 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 based on the annotation you want to update
const INPUT_ID = 'c9cbb1c90cf24bc98bfd2e529e744ca9';
const ANNOTATION_ID = '08d3b9b81432477fb5522d3fb1d1a6f4';
const CONCEPT_ID = 'apple';
const REGION_ID = '361d6a9253be9152968012660258a4bf';

/////////////////////////////////////////////////////////////////////////////
// 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.PatchAnnotations(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        action: "merge",  // Supported actions: overwrite, merge, remove.
        annotations: [
            {
                input_id: INPUT_ID,
                id: ANNOTATION_ID,
                data: {
                    regions: [
                        {
                            id: REGION_ID, // this should be the region id of this annotation before patch
                            // 1 means true, this concept is present.
                            data: {
                                concepts: [
                                    { id: CONCEPT_ID, value: 1 },
                                ]
                            },
                        }
                    ]
                }
            }
        ]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

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

Java (gRPC)

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, input ID, annotation ID, 
    // concept ID, and region 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 these based on the annotation you want to update
    static final String INPUT_ID = "c9cbb1c90cf24bc98bfd2e529e744ca9";
    static final String ANNOTATION_ID = "08d3b9b81432477fb5522d3fb1d1a6f4";
    static final String CONCEPT_ID = "apple";
    static final String REGION_ID = "361d6a9253be9152968012660258a4bf";

    ///////////////////////////////////////////////////////////////////////////////////
    // 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));

        MultiAnnotationResponse patchAnnotationsResponse = stub.patchAnnotations(
            PatchAnnotationsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .setAction("merge") // Supported actions: overwrite, merge, remove
            .addAnnotations(
                Annotation.newBuilder()
                .setInputId(INPUT_ID)
                .setId(ANNOTATION_ID)
                .setData(
                    Data.newBuilder().addRegions(
                        Region.newBuilder()
                        .setId(REGION_ID) // this should be the region id of this annotation
                        .setData(
                            Data.newBuilder().addConcepts(
                                Concept.newBuilder()
                                .setId(CONCEPT_ID)
                                .setValue(1f) // 1 means true, this concept is present
                                .build()
                            )
                        ).build()
                    ).build()
                )
                .build()
            ).build()
        );

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

    }

}

PHP (gRPC)

<?php

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

//////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, input ID, annotation ID, 
// concept ID, and region 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 these based on the annotation you want to update
$INPUT_ID = "c9cbb1c90cf24bc98bfd2e529e744ca9";
$ANNOTATION_ID = "08d3b9b81432477fb5522d3fb1d1a6f4";
$CONCEPT_ID = "apple";
$REGION_ID = "361d6a9253be9152968012660258a4bf";

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

use Clarifai\ClarifaiClient;
use Clarifai\Api\PatchAnnotationsRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Region;
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->PatchAnnotations(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PatchAnnotationsRequest([
        "user_app_id" => $userDataObject, 
        "action" => "merge",  // Supported actions: overwrite, merge, remove
        "annotations" => [
             new Annotation([           
                "input_id" => $INPUT_ID,
                "id" => $ANNOTATION_ID,
                "data" => new Data([
                    "regions" => [
                        new Region([
                            "id" => $REGION_ID, // this should be the region id of this annotation before patch
                            "data" => new Data([
                                "concepts" => [
                                    new Concept([ "id" => $CONCEPT_ID, "value" => 1. ]), // 1 means true, this concept is present
                                ]
                            ])
                        ])
                    ]
                ])
            ]),
        ]
    ]),
    $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());
}

?>

cURL

# Value of 1 means true, this concept is present
# Region ID should be the region ID of this annotation before patch

curl -X PATCH "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "input_id": "YOUR_INPUT_ID_HERE",
        "id": "YOUR_ANNOTATION_ID_HERE",
        "data": {
          "regions": [
            {
              "id": "REGION_ID_HERE",
              "data": {
                "concepts": [
                  {
                    "id": "apple",
                    "value": 1
                  }
                ]
              }
            }
          ]
        }
      }
    ],
    "action":"merge"
}'

Update Annotation Region Coordinates

You can update region bounding boxes coordinates. When changing the region, you should use overwrite action. With overwrite action, you need to provide the data you want to keep in this annotation.

Below is an example of how to do that.

Python (gRPC)

####################################################################################
# In this section, we set the user authentication, app ID, input ID, annotation 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 these based on the annotation you want to update 
INPUT_ID = '53d0362a9dfa4e03b2293375e2d0db73'
ANNOTATION_ID = '300b8e39a65e4f33ae4e15e86eaf4a3b'
CONCEPT_ID = 'bike'

##########################################################################
# 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_annotations_response = stub.PatchAnnotations(
    service_pb2.PatchAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        action="overwrite",
        annotations=[
            resources_pb2.Annotation(
                input_id=INPUT_ID,
                id=ANNOTATION_ID,
                data=resources_pb2.Data(
                    regions=[
                        resources_pb2.Region(
                            region_info=resources_pb2.RegionInfo(
                                bounding_box=resources_pb2.BoundingBox(        # move bounding box to new coordinates
                                    top_row=0.5,
                                    left_col=0.5,
                                    bottom_row=0.8,
                                    right_col=0.8
                                )
                            ),
                            data=resources_pb2.Data(    # need to provide tags you previously labeled since this is overwrite action
                                concepts=[
                                    resources_pb2.Concept(id=CONCEPT_ID, value=1.),  # 1 means true, this concept is present.
                                ]
                            )
                        )
                    ]
                )
            )
        ]
    ),
    metadata=metadata
)

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

JavaScript (REST)

<!--index.html file-->

<script>
    //////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, input ID, annotation 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 based on the annotation you want to update 
    const INPUT_ID = '3232a6fd32544c6a902c2cb0103034ff';
    const ANNOTATION_ID = '3377446a88714ba78654f2cf811c2211';
    const CONCEPT_ID = 'bike';

    ///////////////////////////////////////////////////////////////////////////////////
    // 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
        },
        action: "overwrite",
        "annotations": [
            {
                "data": {
                    "regions": [{
                        "region_info": {
                            "bounding_box": {
                                "top_row": 0,
                                "left_col": 0,
                                "bottom_row": 1,
                                "right_col": 1
                            }
                        },
                        "data": {
                            "concepts": [{
                                "id": CONCEPT_ID,
                                "value": 1
                            }]
                        }
                    }]
                },
                "input_id": INPUT_ID,
                "id": ANNOTATION_ID
            }
        ]
    });

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

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

</script>

Node.js (gRPC)

//index.js file

//////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, input ID, annotation 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 based on the annotation you want to update 
const INPUT_ID = '3232a6fd32544c6a902c2cb0103034ff';
const ANNOTATION_ID = '3377446a88714ba78654f2cf811c2211';
const CONCEPT_ID = 'bike';

/////////////////////////////////////////////////////////////////////////////
// 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.PatchAnnotations(
    {

        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        action: "overwrite",
        annotations: [
            {
                input_id: INPUT_ID,
                id: ANNOTATION_ID,
                data: {
                    regions: [
                        {
                            region_info: {
                                bounding_box: {        // move bounding box to a new coordiates
                                    top_row: 0.5,
                                    left_col: 0.5,
                                    bottom_row: 0.8,
                                    right_col: 0.8
                                }
                            },
                            // 1 means true, this concept is present.
                            // 0 means false, this concept is not present.
                            data: {
                                concepts: [
                                    { id: CONCEPT_ID, value: 1 },
                                ]
                            },
                        }
                    ]
                }
            }
        ]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

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

Java (gRPC)

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, input ID, annotation 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 these based on the annotation you want to update 
    static final String INPUT_ID = "3232a6fd32544c6a902c2cb0103034ff";
    static final String ANNOTATION_ID = "3377446a88714ba78654f2cf811c2211";
    static final String CONCEPT_ID = "bike";

    ///////////////////////////////////////////////////////////////////////////////////
    // 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));

        MultiAnnotationResponse patchAnnotationsResponse = stub.patchAnnotations(
            PatchAnnotationsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .setAction("overwrite")
            .addAnnotations(
                Annotation.newBuilder()
                .setInputId(INPUT_ID)
                .setId(ANNOTATION_ID)
                .setData(
                    Data.newBuilder().addRegions(
                        Region.newBuilder()
                        .setRegionInfo(
                            RegionInfo.newBuilder()
                            .setBoundingBox( // move bounding box to a new coordinates
                                BoundingBox.newBuilder()
                                .setTopRow(0.5f)
                                .setLeftCol(0.5f)
                                .setBottomRow(0.8f)
                                .setRightCol(0.8f)
                                .build()
                            )
                            .build()
                        )
                        .setData(
                            Data.newBuilder()
                            .addConcepts(
                                Concept.newBuilder()
                                .setId(CONCEPT_ID)
                                .setValue(1f) // 1 means true, this concept is present
                                .build()
                            )
                        ).build()
                    ).build()
                )
                .build()
            ).build()
        );

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

    }

}

PHP (gRPC)

<?php

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

//////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, input ID, annotation 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 these based on the annotation you want to update 
$INPUT_ID = "3232a6fd32544c6a902c2cb0103034ff";
$ANNOTATION_ID = "3377446a88714ba78654f2cf811c2211";
$CONCEPT_ID = "bike";

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

use Clarifai\ClarifaiClient;
use Clarifai\Api\PatchAnnotationsRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\BoundingBox;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Region;
use Clarifai\Api\RegionInfo;
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->PatchAnnotations(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PatchAnnotationsRequest([
        "user_app_id" => $userDataObject, 
        "action" => "overwrite",
        "annotations" => [
             new Annotation([
                "input_id" => $INPUT_ID,
                "id" => $ANNOTATION_ID,
                "data" => new Data([
                    "regions" => [
                        new Region([
                            "region_info" => new RegionInfo([
                                "bounding_box" => new BoundingBox([  // move bounding box to new coordinates
                                    "top_row" => 0.5,
                                    "left_col" => 0.5,
                                    "bottom_row" => 0.8,
                                    "right_col" => 0.8
                                ])                                
                            ]),
                            "data" => new Data([  // need to provide tags you previously labeled since this is overwrite action
                                "concepts" => [
                                    new Concept([ "id" => $CONCEPT_ID, "value" => 1. ]), // 1 means true, this concept is present
                                ]
                            ])
                        ])
                    ]
                ])
            ]),            
        ]
    ]),
    $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());
}

?>

cURL

curl -X PATCH "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
            {
                "data": {
                    "regions": [{
                        "region_info": {
                            "bounding_box": {
                                "top_row": 0,
                                "left_col": 0,
                                "bottom_row": 1,
                                "right_col": 1
                            }
                        },
                        "data": {
                            "concepts": [{
                                "id": "bike",
                                "value": 1
                            }]
                        }
                    }]
                },
                "input_id": "YOUR_INPUT_ID_HERE",
                "id": "YOUR_ANNOTATION_ID_HERE"
            }
        ],
    "action":"overwrite"
}'

Update Annotation Status

Below is an example of how to update an annotation status.

Python (gRPC)

#############################################################################
# In this section, we set the user authentication, app ID, input ID, and  
# annotation 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 these based on the annotation status you want to update
INPUT_ID = 'c021c670357e4083b197abe80bda82b0'
ANNOTATION_ID = '8ac7fd96ce6f44b8a0f4806488b41b93'

##########################################################################
# 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, status_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_annotations_response = stub.PatchAnnotations(
    service_pb2.PatchAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        action="merge",  # Supported actions: overwrite, merge, remove.
        annotations=[
            resources_pb2.Annotation(
                input_id=INPUT_ID,
                id=ANNOTATION_ID,
                status=status_pb2.Status(
                    code=status_code_pb2.ANNOTATION_SUCCESS
                )
            )
        ]
    ),
    metadata=metadata
)

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

JavaScript (REST)

<!--index.html file-->

<script>
    ////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, input ID, and  
    // annotation 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 based on the annotation status you want to update
    const INPUT_ID = '3232a6fd32544c6a902c2cb0103034ff';
    const ANNOTATION_ID = '3377446a88714ba78654f2cf811c2211';

    ///////////////////////////////////////////////////////////////////////////////////
    // 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
        },
        "annotations": [
            {
                "input_id": INPUT_ID,
                "id": ANNOTATION_ID,
                "status": {
                    "code": "ANNOTATION_SUCCESS"
                }
            }
        ],
        "action": "merge"
    });

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

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

</script>

Node.js (gRPC)

//index.js file

////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, input ID, and  
// annotation 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 based on the annotation status you want to update
const INPUT_ID = '3232a6fd32544c6a902c2cb0103034ff';
const ANNOTATION_ID = '3377446a88714ba78654f2cf811c2211';

/////////////////////////////////////////////////////////////////////////////
// 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.PatchAnnotations(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        action: "merge",  // Supported actions: overwrite, merge, remove.
        annotations: [
            {
                input_id: INPUT_ID,
                id: ANNOTATION_ID,
                status: {
                    code: 24150
                }
            }
        ]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

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

Java (gRPC)

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.Status;
import com.clarifai.grpc.api.status.StatusCode;

public class ClarifaiExample {

    //////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, input ID, and  
    // annotation 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 these based on the annotation status you want to update
    static final String INPUT_ID = "3232a6fd32544c6a902c2cb0103034ff";
    static final String ANNOTATION_ID = "3377446a88714ba78654f2cf811c2211";

    ///////////////////////////////////////////////////////////////////////////////////
    // 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));

        MultiAnnotationResponse patchAnnotationsResponse = stub.patchAnnotations(
            PatchAnnotationsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .setAction("merge") // Supported actions: overwrite, merge, remove
            .addAnnotations(
                Annotation.newBuilder()
                .setInputId(INPUT_ID)
                .setId(ANNOTATION_ID)
                .setStatus(
                    Status.newBuilder()
                    .setCodeValue(StatusCode.ANNOTATION_SUCCESS_VALUE)
                    .build()
                )
                .build()
            ).build()
        );

        if (patchAnnotationsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("patch annotations failed, status: " + patchAnnotationsResponse.getStatus());
        }

    }

}

PHP (gRPC)

<?php

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

////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, input ID, and  
// annotation 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 these based on the annotation status you want to update
$INPUT_ID = "3232a6fd32544c6a902c2cb0103034ff";
$ANNOTATION_ID = "3377446a88714ba78654f2cf811c2211";

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

use Clarifai\ClarifaiClient;
use Clarifai\Api\PatchAnnotationsRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Status\Status;
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->PatchAnnotations(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PatchAnnotationsRequest([
        "user_app_id" => $userDataObject, 
        "action" => "merge",  // Supported actions: overwrite, merge, remove
        "annotations" => [
             new Annotation([
                "input_id" => $INPUT_ID,
                "id" => $ANNOTATION_ID,
                "status" => new Status([
                    "code" => StatusCode::ANNOTATION_SUCCESS
                ])      
            ])         
        ]
    ]),
    $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());
}

?>

cURL

curl -X PATCH "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "input_id": "YOUR_INPUT_ID_HERE",
        "id": "YOUR_ANNOTATION_ID_HERE",
        "status": {
          "code": "ANNOTATION_SUCCESS"
        }
      }
    ],
    "action":"merge"
}'