Classify

POST/v1/classifyClassify

This endpoint makes a prediction about which label fits the specified text inputs best. To make a prediction, Classify uses the provided examples of text + label pairs as a reference. Note: Fine-tuned models trained on classification examples don't require the examples parameter to be passed in explicitly.

Parameters

X-Client-Namestringheader

The name of the project that is making the request.

Request body

application/json

object

examplesarray of object

An array of examples to provide context to the model. Each example is a text string and its associated label/class. Each unique label requires at least 2 examples associated with it; the maximum number of examples is 2500, and each example has a maximum length of 512 tokens. The values should be structured as `{text: "...",label: "..."}`. Note: [Fine-tuned Models](https://docs.cohere.com/docs/classify-fine-tuning) trained on classification examples don't require the `examples` parameter to be passed in explicitly.

maxItems 2500

Show child attributes

maxItems 2500

Show array items

labelstring

textstring

inputsarray of stringrequired

A list of up to 96 texts to be classified. Each one must be a non-empty string. There is, however, no consistent, universal limit to the length a particular input can be. We perform classification on the first `x` tokens of each input, and `x` varies depending on which underlying model is powering classification. The maximum token length for each model is listed in the "max tokens" column [here](https://docs.cohere.com/docs/models). Note: by default the `truncate` parameter is set to `END`, so tokens exceeding the limit will be automatically dropped. This behavior can be disabled by setting `truncate` to `NONE`, which will result in validation errors for longer texts.

maxItems 96

Show child attributes

maxItems 96

modelstring

ID of a [Fine-tuned](https://docs.cohere.com/v2/docs/classify-starting-the-training) Classify model

presetstring

The ID of a custom playground preset. You can create presets in the [playground](https://dashboard.cohere.com/playground). If you use a preset, all other parameters become optional, and any included parameters will override the preset's parameters.

truncatestring

One of `NONE|START|END` to specify how the API will handle inputs longer than the maximum token length. Passing `START` will discard the start of the input. `END` will discard the end of the input. In both cases, input is discarded until the remaining input is exactly the maximum input token length for the model. If `NONE` is selected, when the input exceeds the maximum input token length an error will be returned.

one of "NONE", "START", "END" · default "END"

Example request

{
  "examples": [
    {
      "label": "string",
      "text": "string"
    }
  ],
  "inputs": [
    "string"
  ],
  "model": "string",
  "preset": "my-preset-a58sbd",
  "truncate": "END"
}

Responses

Headers

X-API-Warning

Warning description for incorrect usage of the API

object

classificationsarray of objectrequired

Show child attributes

Show array items

classification_typestringrequired

The type of classification performed

one of "single-label", "multi-label"

confidencenumber · float

The confidence score for the top predicted class (only filled for single-label classification)

confidencesarray of number · floatrequired

An array containing the confidence scores of all the predictions in the same order

Show child attributes

idstringrequired

inputstring

The input text that was classified

labelsobjectrequired

A map containing each label and its confidence score according to the classifier. All the confidence scores add up to 1 for single-label classification. For multi-label classification the label confidences are independent of each other, so they don't have to sum up to 1.

predictionstring

The predicted label for the associated query (only filled for single-label models)

predictionsarray of stringrequired

An array containing the predicted labels for the associated query (only filled for single-label classification)

Show child attributes

idstringrequired

metaobject

Show child attributes

api_versionobject

Show child attributes

is_deprecatedboolean

is_experimentalboolean

versionstringrequired

billed_unitsobject

Show child attributes

classificationsnumber

The number of billed classifications units.

image_tokensnumber

The number of billed image tokens.

imagesnumber

The number of billed images.

input_tokensnumber

The number of billed input tokens.

output_tokensnumber

The number of billed output tokens.

pagesnumber

The number of billed pages parsed.

search_unitsnumber

The number of billed search units.

cached_tokensnumber

The number of prompt tokens that hit the inference cache.

tokensobject

Show child attributes

input_tokensnumber

The number of tokens used as input to the model.

output_tokensnumber

The number of tokens produced by the model.

warningsarray of string

Show child attributes

Example response

{
  "classifications": [
    {
      "classification_type": "multi-label",
      "confidence": 0,
      "confidences": [
        0
      ],
      "id": "string",
      "input": "string",
      "labels": {
        "additionalProp1": {
          "confidence": 0
        }
      },
      "prediction": "string",
      "predictions": [
        "string"
      ]
    }
  ],
  "id": "string",
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  }
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

Examples

X-Client-Nameheader parameter

curl -X POST 'https://api.cohere.com/v1/classify' \
  -H 'Content-Type: application/json' \
  -d '{"examples":[{"label":"string","text":"string"}],"inputs":["string"],"model":"string","preset":"my-preset-a58sbd","truncate":"END"}'

const response = await fetch('https://api.cohere.com/v1/classify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"examples":[{"label":"string","text":"string"}],"inputs":["string"],"model":"string","preset":"my-preset-a58sbd","truncate":"END"}),
});
const data = await response.json();

const response = await fetch('https://api.cohere.com/v1/classify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"examples\":[{\"label\":\"string\",\"text\":\"string\"}],\"inputs\":[\"string\"],\"model\":\"string\",\"preset\":\"my-preset-a58sbd\",\"truncate\":\"END\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.cohere.com/v1/classify",
    headers={"Content-Type": "application/json"},
    data='{"examples":[{"label":"string","text":"string"}],"inputs":["string"],"model":"string","preset":"my-preset-a58sbd","truncate":"END"}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"examples":[{"label":"string","text":"string"}],"inputs":["string"],"model":"string","preset":"my-preset-a58sbd","truncate":"END"}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.cohere.com/v1/classify", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://api.cohere.com/v1/classify");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"examples\":[{\"label\":\"string\",\"text\":\"string\"}],\"inputs\":[\"string\"],\"model\":\"string\",\"preset\":\"my-preset-a58sbd\",\"truncate\":\"END\"}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.cohere.com/v1/classify"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"examples\":[{\"label\":\"string\",\"text\":\"string\"}],\"inputs\":[\"string\"],\"model\":\"string\",\"preset\":\"my-preset-a58sbd\",\"truncate\":\"END\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.cohere.com/v1/classify")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"examples\":[{\"label\":\"string\",\"text\":\"string\"}],\"inputs\":[\"string\"],\"model\":\"string\",\"preset\":\"my-preset-a58sbd\",\"truncate\":\"END\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cohere.com/v1/classify");
request.Content = new StringContent("{\"examples\":[{\"label\":\"string\",\"text\":\"string\"}],\"inputs\":[\"string\"],\"model\":\"string\",\"preset\":\"my-preset-a58sbd\",\"truncate\":\"END\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "classifications": [
    {
      "classification_type": "multi-label",
      "confidence": 0,
      "confidences": [
        0
      ],
      "id": "string",
      "input": "string",
      "labels": {
        "additionalProp1": {
          "confidence": 0
        }
      },
      "prediction": "string",
      "predictions": [
        "string"
      ]
    }
  ],
  "id": "string",
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  }
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

Search documentation

/datasets

/connectors

/embed-jobs

/finetuning

/models

/audio/transcriptions

/batches

Operations

Parameters

Request body

Responses

Headers

/datasets

/connectors

/embed-jobs

/finetuning

/models

/audio/transcriptions

/batches

Operations