Categorize¶

Categorize documents into one or more categories using AI-powered semantic understanding.

Categorization is multilingual, works across all supported languages.

Categorize vs. Classify vs. Predict

See this page for details on selecting the right endpoint for your classification task.

Endpoint¶

POST /v20241104/categorize

API Request¶

Required Parameters

document_id array of strings

Array specifying one or more document IDs.

Info

Example (single document ID):

"document_id": ["4nD1gZIB7caKVIeL2MgL"]

Example (multiple document IDs):

"document_id": ["4nD1gZIB7caKVIeL2MgL", "4wdRU5QBP4_EawzZupIF"]

For each document ID string:

MinLength: 1 MaxLength: 128

MinLength: 1 MaxLength: 10

categories array of objects

An array of JSON objects specifying the categories.

Info

Example:

"categories": [
    {
        "name": "Alpacas",
        "description": "Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors."
    },
    {
        "name": "Wildebeests",
        "description": "Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane."
    },
    {
        "name": "Cheetahs",
        "description": "Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal."
    }
]

For each category:
- name (string): 1 - 100 characters
- description (string): 100 - 500 characters
Longer descriptions will result in more accurate category assignment.

MinLength: 1 MaxLength: 20

Optional Parameters

max_categories integer

Maximum number of categories to assign for each document.

Default is 1.

Min: 1 Max: 5

min_confidence_level string (enum)

Minimum confidence level for a category to be assigned.

Default is medium.

Allowed values: very_high | high | medium

POST /v20241104/categorize

cURLAI PromptC#GoJavaNode.jsPHPPythonRuby

curl -X POST "https://api.gainly.ai/v20241104/categorize" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \  # (1)!
  -d '{
    "document_id": ["Y1YrdJQBQ1TpH-jr-QPG"],
    "categories": [
        {
            "name": "Alpacas",
            "description": "Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors."
        },
        {
            "name": "Wildebeests",
            "description": "Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane."
        },
        {
            "name": "Cheetahs",
            "description": "Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal."
        }
    ]
  }'

Replace YOUR_API_KEY_HERE with the value of your API key.

# Prompt for AI coding assistants/IDEs (e.g., ChatGPT, Claude, GitHub Copilot, Cursor, Windsurf)

Using the Gainly API:
1. Write code to call the categorize operation (see OpenAPI spec: https://api.gainly.ai/v20241104/openapi.json)
2. Implement authentication using the header "X-API-Key" as described in the docs: https://docs.gainly.ai/latest/api-reference/authentication/
3. Implement rate limit handling as described in the docs: https://docs.gainly.ai/latest/api-reference/rate-limits/
4. Implement error handling
5. Handle the response according to the CategorizeResults schema in the OpenAPI spec

using System.Net.Http;
using System.Text.Json;
using System.Text;

var client = new HttpClient();

var url = "https://api.gainly.ai/v20241104/categorize";

var payload = new {
    document_id = new[] { "Y1YrdJQBQ1TpH-jr-QPG" },
    categories = new[] {
        new {
            name = "Alpacas",
            description = "Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors."
        },
        new {
            name = "Wildebeests",
            description = "Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane."
        },
        new {
            name = "Cheetahs",
            description = "Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal."
        }
    }
};

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY_HERE"); // (1)!

var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Replace YOUR_API_KEY_HERE with the value of your API key.

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://api.gainly.ai/v20241104/categorize"

    payload := map[string]interface{}{
        "document_id": []string{"Y1YrdJQBQ1TpH-jr-QPG"},
        "categories": []map[string]string{
            {
                "name": "Alpacas",
                "description": "Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors.",
            },
            {
                "name": "Wildebeests",
                "description": "Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane.",
            },
            {
                "name": "Cheetahs",
                "description": "Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal.",
            }
        },
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY_HERE") // (1)!

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}

Replace YOUR_API_KEY_HERE with the value of your API key.

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

var client = HttpClient.newHttpClient();

var url = "https://api.gainly.ai/v20241104/categorize";

var payload = """
    {
        "document_id": ["Y1YrdJQBQ1TpH-jr-QPG"],
        "categories": [
            {
                "name": "Alpacas",
                "description": "Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors."
            },
            {
                "name": "Wildebeests",
                "description": "Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane."
            },
            {
                "name": "Cheetahs",
                "description": "Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal."
            }
        ]
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "application/json")
    .header("X-API-Key", "YOUR_API_KEY_HERE") // (1)!
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Replace YOUR_API_KEY_HERE with the value of your API key.

const axios = require('axios');  // or: import axios from 'axios';

const url = 'https://api.gainly.ai/v20241104/categorize';

const payload = {
    document_id: ['Y1YrdJQBQ1TpH-jr-QPG'],
    categories: [
        {
            name: 'Alpacas',
            description: 'Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors.'
        },
        {
            name: 'Wildebeests',
            description: 'Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane.'
        },
        {
            name: 'Cheetahs',
            description: 'Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal.'
        }
    ]
};

const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY_HERE' // (1)!
};

axios.post(url, payload, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error.message));

Replace YOUR_API_KEY_HERE with the value of your API key.

<?php

$client = new \GuzzleHttp\Client();

$url = 'https://api.gainly.ai/v20241104/categorize';

$payload = [
    'document_id' => ['Y1YrdJQBQ1TpH-jr-QPG'],
    'categories' => [
        [
            'name' => 'Alpacas',
            'description' => 'Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors.'
        ],
        [
            'name' => 'Wildebeests',
            'description' => 'Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane.'
        ],
        [
            'name' => 'Cheetahs',
            'description' => 'Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal.'
        ]
    ]
];

$response = $client->request('POST', $url, [
    'json' => $payload,
    'headers' => [
        'Content-Type' => 'application/json',
        'X-API-Key' => 'YOUR_API_KEY_HERE' # (1)!
    ],
]);

echo $response->getBody();

Replace YOUR_API_KEY_HERE with the value of your API key.

import requests

url = "https://api.gainly.ai/v20241104/categorize"

payload = {
    "document_id": ["Y1YrdJQBQ1TpH-jr-QPG"],
    "categories": [
        {
            "name": "Alpacas",
            "description": "Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors."
        },
        {
            "name": "Wildebeests",
            "description": "Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane."
        },
        {
            "name": "Cheetahs",
            "description": "Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal."
        }
    ]
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY_HERE" # (1)!
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)

Replace YOUR_API_KEY_HERE with the value of your API key.

require 'json'
require 'uri'
require 'net/http'
require 'openssl'

url = URI('https://api.gainly.ai/v20241104/categorize')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = 'YOUR_API_KEY_HERE' # (1)!
request.body = {
    document_id: ['Y1YrdJQBQ1TpH-jr-QPG'],
    categories: [
        {
            name: 'Alpacas',
            description: 'Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors.'
        },
        {
            name: 'Wildebeests',
            description: 'Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane.'
        },
        {
            name: 'Cheetahs',
            description: 'Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal.'
        }
    ]
}.to_json

response = http.request(request)
puts response.read_body

Replace YOUR_API_KEY_HERE with the value of your API key.

API Response¶

{
    "object": "categorize_result",
    "url": "/v20241104/categorize",
    "data": [
        {
            "id": "Y1YrdJQBQ1TpH-jr-QPG",
            "title": "Velocidad del Guepardo: La Ciencia Detrás del Animal Terrestre Más Rápido",
            "categories": [
                {
                    "name": "Cheetahs",
                    "confidence_level": "high"
                }
            ]
        }
    ],
    "document_id": [
        "Y1YrdJQBQ1TpH-jr-QPG"
    ],
    "categories": [
        {
            "name": "Alpacas",
            "description": "Alpacas are domesticated, social animals native to South America, primarily found in the Andes. Known for their soft, luxurious fleece, alpacas are smaller than llamas and come in a variety of colors."
        },
        {
            "name": "Wildebeests",
            "description": "Wildebeests, also known as gnus, are large, social antelopes native to Africa, commonly found in grasslands and savannas. Recognized for their robust build, distinct curved horns, and shaggy mane."
        },
        {
            "name": "Cheetahs",
            "description": "Cheetahs, also known as hunting leopards, are swift, solitary cats native to Africa, commonly found in open grasslands and savannas. Recognized for their slender build, distinctive spotted coat, and unmatched speed as the fastest land animal."
        }
    ],
    "max_categories": 1,
    "min_confidence_level": "medium",
    "token_usage": {
        "semantic_tokens": 445,
        "llm_tokens": {
            "llm_output_tokens": 0,
            "llm_input_tokens": 0,
            "model": null
        }
    },
    "livemode": false
}

Confidence Level¶

confidence_level represents Gainly's assessment of how likely a document is to belong to a category.

"data": [
    {
        "id": "Y1YrdJQBQ1TpH-jr-QPG",
        "title": "Velocidad del Guepardo: La Ciencia Detrás del Animal Terrestre Más Rápido",
        "categories": [
            {
                "name": "Cheetahs",
                "confidence_level": "high"
            }
        ]
    }
],

It will have one of the following values:

very_high
high
medium