Operations (sample payloads)

Main operations
Copy

Generate Chat (Beta)
Copy

Generates a text response to a user message.

Sample Input

1
{
2
"body": {
3
"message": "What are the main differences between Python and JavaScript?",
4
"model": "command",
5
"temperature": 0.3,
6
"max_tokens": 150,
7
"connectors": [
8
{
9
"id": "web-search"
10
}
11
]
12
}
13
}

Sample Output

1
{
2
"text": "The main differences between Python and JavaScript are:\n\n1. Language type: Python is a general-purpose programming language, while JavaScript is primarily a scripting language for web development.\n\n2. Execution environment: Python runs on servers or as standalone applications, while JavaScript primarily runs in web browsers (though it can also run on servers with Node.js).\n\n3. Syntax: Python uses indentation for code blocks, while JavaScript uses curly braces.\n\n4. Data types: Python has more built-in data types and supports static typing with type hints, while JavaScript is dynamically typed.\n\n5. Object-oriented programming: Both support OOP, but Python's implementation is more straightforward and traditional.",
3
"generation_id": "gen-2023-05-15-12-34-56-789",
4
"citations": [],
5
"documents": [],
6
"is_search_required": true,
7
"search_queries": [
8
{
9
"text": "main differences between Python and JavaScript",
10
"generation_id": "gen-2023-05-15-12-34-56-790"
11
}
12
],
13
"search_results": [
14
{
15
"search_query": {
16
"text": "main differences between Python and JavaScript",
17
"generation_id": "gen-2023-05-15-12-34-56-790"
18
},
19
"connector": {
20
"id": "web-search"
21
},
22
"document_ids": [
23
"doc-001",
24
"doc-002",
25
"doc-003"
26
]
27
}
28
],
29
"finish_reason": "max_tokens"
30
}

Generate Classification
Copy

This endpoint makes a prediction about which label fits the specified text inputs best.

Sample Input

1
{
2
"body": {
3
"inputs": [
4
"Get rich quick! Invest now!",
5
"Thank you for your purchase. Your order will be shipped tomorrow.",
6
"URGENT: Your account has been locked. Click here to verify."
7
],
8
"examples": [
9
{
10
"text": "Win a free iPhone! Click here!",
11
"label": "Spam"
12
},
13
{
14
"text": "Your package has been delivered.",
15
"label": "Not spam"
16
},
17
{
18
"text": "Meeting rescheduled to 3 PM tomorrow.",
19
"label": "Not spam"
20
}
21
],
22
"model": "embed-english-v2.0",
23
"truncate": "END"
24
}
25
}

Sample Output

1
{
2
"id": "8f7b3e9a-c1d2-4e3f-a5b6-7c8d9e0f1a2b",
3
"classifications": [
4
{
5
"id": "clf-1",
6
"input": "Get rich quick! Invest now!",
7
"prediction": "Spam",
8
"predictions": [
9
"Spam",
10
"Not spam"
11
],
12
"confidence": 0.95,
13
"confidences": [
14
0.95,
15
0.05
16
],
17
"labels": {
18
"Not spam": {
19
"confidence": 0.05
20
},
21
"Spam": {
22
"confidence": 0.95
23
}
24
},
25
"classification_type": "multiclass"
26
},
27
{
28
"id": "clf-2",
29
"input": "Thank you for your purchase. Your order will be shipped tomorrow.",
30
"prediction": "Not spam",
31
"predictions": [
32
"Not spam",
33
"Spam"
34
],
35
"confidence": 0.98,
36
"confidences": [
37
0.98,
38
0.02
39
],
40
"labels": {
41
"Not spam": {
42
"confidence": 0.98
43
},
44
"Spam": {
45
"confidence": 0.02
46
}
47
},
48
"classification_type": "multiclass"
49
},
50
{
51
"id": "clf-3",
52
"input": "URGENT: Your account has been locked. Click here to verify.",
53
"prediction": "Spam",
54
"predictions": [
55
"Spam",
56
"Not spam"
57
],
58
"confidence": 0.89,
59
"confidences": [
60
0.89,
61
0.11
62
],
63
"labels": {
64
"Not spam": {
65
"confidence": 0.11
66
},
67
"Spam": {
68
"confidence": 0.89
69
}
70
},
71
"classification_type": "multiclass"
72
}
73
],
74
"meta": {
75
"api_version": {
76
"version": 1
77
}
78
}
79
}

Generate Detokenized Text
Copy

This endpoint takes tokens using byte-pair encoding and returns their text representation.

Sample Input

1
{
2
"body": {
3
"tokens": [
4
1234,
5
5678,
6
9012,
7
3456
8
],
9
"model": "command"
10
},
11
"headers": {
12
"X-Client-Name": "MyProject"
13
}
14
}

Sample Output

1
{
2
"text": "The quick brown fox jumps over the lazy dog.",
3
"meta": {
4
"api_version": {
5
"version": 1
6
}
7
}
8
}

Generate Text
Copy

This endpoint generates realistic text conditioned on a given input.

Sample Input

1
{
2
"body": {
3
"prompt": "Write a short story about a robot learning to paint:",
4
"model": "command",
5
"num_generations": 1,
6
"max_tokens": 150,
7
"temperature": 0.7,
8
"stop_sequences": [
9
"The end."
10
],
11
"return_likelihoods": "NONE"
12
}
13
}

Sample Output

1
{
2
"id": "8f5d0e3a-7c1d-4f3b-9c6a-1c2b3d4e5f6g",
3
"generations": [
4
{
5
"id": "gen-1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
6
"text": "In a world of steel and circuits, a robot named Pixel discovered an old set of paints. Curiosity sparked in its processors, and it began to experiment. At first, Pixel's attempts were clumsy, splattering colors haphazardly. But with each brushstroke, its algorithms adapted, learning the nuances of texture and shade. Soon, Pixel was creating beautiful landscapes, its mechanical precision blending with newfound creativity. The robot had not just learned to paint; it had discovered the joy of art.",
7
"index": 0,
8
"likelihood": 0.95,
9
"token_likelihoods": []
10
}
11
],
12
"prompt": "Write a short story about a robot learning to paint:",
13
"meta": {
14
"api_version": {
15
"version": "1.0",
16
"is_deprecated": false,
17
"is_experimental": false
18
},
19
"billed_units": {
20
"input_tokens": 8,
21
"output_tokens": 84,
22
"search_units": 0,
23
"classifications": 0
24
},
25
"warnings": []
26
}
27
}

Generate Text Embeddings
Copy

This endpoint returns text embeddings.

Sample Input

1
{
2
"body": {
3
"texts": [
4
"The quick brown fox jumps over the lazy dog",
5
"Machine learning is a subset of artificial intelligence"
6
],
7
"model": "embed-english-v3.0",
8
"input_type": "classification",
9
"embedding_types": [
10
"float"
11
],
12
"truncate": "END"
13
}
14
}

Sample Output

1
{
2
"response_type": "text_embedding",
3
"id": "8f7b9a1c-3d2e-4f6a-9b8c-7d6e5f4a3b2c",
4
"embeddings": [
5
[
6
0.023,
7
-0.041,
8
0.012,
9
0.067,
10
-0.089,
11
0.105,
12
-0.032,
13
0.076
14
],
15
[
16
0.056,
17
0.018,
18
-0.072,
19
0.094,
20
0.037,
21
-0.061,
22
0.083,
23
-0.029
24
]
25
],
26
"texts": [
27
"The quick brown fox jumps over the lazy dog",
28
"Machine learning is a subset of artificial intelligence"
29
],
30
"meta": {
31
"api_version": {
32
"version": "1.0",
33
"is_deprecated": false,
34
"is_experimental": false
35
},
36
"billed_units": {
37
"input_tokens": 18,
38
"output_tokens": 0,
39
"search_units": 0,
40
"classifications": 0
41
},
42
"warnings": []
43
}
44
}

Generate Tokens
Copy

This endpoint splits input text into smaller units called tokens using byte-pair encoding (BPE).

Sample Input

1
{
2
"body": {
3
"text": "The quick brown fox jumps over the lazy dog.",
4
"model": "command"
5
}
6
}

Sample Output

1
{
2
"tokens": [
3
2,
4
262,
5
1658,
6
1382,
7
6827,
8
284,
9
262,
10
3100,
11
1382
12
],
13
"token_strings": [
14
"The",
15
" quick",
16
" brown",
17
" fox",
18
" jumps",
19
" over",
20
" the",
21
" lazy",
22
" dog."
23
],
24
"meta": {
25
"api_version": {
26
"version": 1
27
}
28
}
29
}

List Models
Copy

Returns a list of models available for use. The list contains models from Cohere as well as your fine-tuned models.

Sample Input

1
{
2
"page_size": 5,
3
"page_token": "abc123xyz",
4
"endpoint": "generate"
5
}

Sample Output

1
{
2
"models": [
3
{
4
"name": "command",
5
"endpoints": [
6
"generate",
7
"chat"
8
],
9
"finetuned": false,
10
"context_length": 4096
11
},
12
{
13
"name": "command-light",
14
"endpoints": [
15
"generate",
16
"chat"
17
],
18
"finetuned": false,
19
"context_length": 4096
20
},
21
{
22
"name": "base",
23
"endpoints": [
24
"generate"
25
],
26
"finetuned": false,
27
"context_length": 2048
28
},
29
{
30
"name": "custom-model-v1",
31
"endpoints": [
32
"generate"
33
],
34
"finetuned": true,
35
"context_length": 2048
36
},
37
{
38
"name": "summarize-medium",
39
"endpoints": [
40
"summarize"
41
],
42
"finetuned": false,
43
"context_length": 4096
44
}
45
],
46
"next_page_token": "def456uvw"
47
}

Raw HTTP request (advanced)
Copy

Perform a raw HTTP request with some pre-configuration and processing by the connector, such as authentication.

Sample Input

1
{
2
"method": "POST",
3
"url": {
4
"fullUrl": "https://api.cohere.ai/v1/classify"
5
},
6
"headers": {
7
"Content-Type": "application/json",
8
"Authorization": "Bearer your-api-key-here"
9
},
10
"body": {
11
"raw": {
12
"inputs": [
13
"The food was delicious!"
14
],
15
"examples": [
16
{
17
"text": "The service was excellent",
18
"label": "positive"
19
},
20
{
21
"text": "The wait was too long",
22
"label": "negative"
23
},
24
{
25
"text": "I would recommend this restaurant",
26
"label": "positive"
27
},
28
{
29
"text": "The food was cold",
30
"label": "negative"
31
}
32
],
33
"model": "large",
34
"task_description": "Classify restaurant reviews as positive or negative"
35
}
36
}
37
}

Sample Output

1
{
2
"status": 200,
3
"headers": {
4
"Content-Type": "application/json",
5
"X-Request-ID": "abcd1234efgh5678"
6
},
7
"body": {
8
"classifications": [
9
{
10
"id": "7f2ce710-f5b7-4f7c-a714-8b9f6b1e6c64",
11
"input": "The food was delicious!",
12
"prediction": "positive",
13
"confidence": 0.9876,
14
"labels": {
15
"positive": 0.9876,
16
"negative": 0.0124
17
}
18
}
19
],
20
"meta": {
21
"api_version": {
22
"version": "1"
23
}
24
}
25
}
26
}

Summarize Text
Copy

This endpoint generates a summary in English for a given text.

Sample Input

1
{
2
"body": {
3
"text": "Artificial intelligence (AI) is intelligence demonstrated by machines, as opposed to natural intelligence displayed by animals including humans. AI research has been defined as the field of study of intelligent agents, which refers to any system that perceives its environment and takes actions that maximize its chance of achieving its goals. The term 'artificial intelligence' is often used to describe machines (or computers) that mimic 'cognitive' functions that humans associate with the human mind, such as 'learning' and 'problem solving'. As machines become increasingly capable, tasks considered to require 'intelligence' are often removed from the definition of AI, a phenomenon known as the AI effect. A quip in Tesler's Theorem says 'AI is whatever hasn't been done yet.' For instance, optical character recognition is frequently excluded from things considered to be AI, having become a routine technology.",
4
"length": "short",
5
"format": "paragraph",
6
"model": "command",
7
"extractiveness": "medium",
8
"temperature": 0.7
9
},
10
"headers": {
11
"X-Client-Name": "AI-Documentation-Project"
12
}
13
}

Sample Output

1
{
2
"id": "8f9a2b3c-4d5e-6f7g-8h9i-0j1k2l3m4n5o",
3
"summary": "Artificial Intelligence (AI) is machine-demonstrated intelligence, contrasting with natural intelligence in animals and humans. It involves the study of intelligent agents that perceive their environment and act to achieve goals. AI often mimics human cognitive functions like learning and problem-solving. As AI capabilities advance, previously considered 'intelligent' tasks may be excluded from its definition, known as the AI effect.",
4
"meta": {
5
"api_version": {
6
"version": "1.0",
7
"is_deprecated": false,
8
"is_experimental": false
9
},
10
"billed_units": {
11
"input_tokens": 156,
12
"output_tokens": 62,
13
"search_units": 0,
14
"classifications": 0
15
},
16
"warnings": []
17
}
18
}

DDL operations
Copy

List Models (DDL)
Copy

Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping

Sample Input

1
{
2
"page_size": 10,
3
"page_token": "next_page_token_123",
4
"endpoint": "https://api.cohere.ai/v1/models"
5
}

Sample Output

1
{
2
"result": [
3
{
4
"text": "GPT-3",
5
"value": "gpt3"
6
},
7
{
8
"text": "BERT",
9
"value": "bert"
10
},
11
{
12
"text": "T5",
13
"value": "t5"
14
},
15
{
16
"text": "XLNet",
17
"value": "xlnet"
18
},
19
{
20
"text": "RoBERTa",
21
"value": "roberta"
22
}
23
]
24
}