Skip to content

Add Document

Adds a document to your semantic index.

Endpoint

POST /v20241104/documents

API Request

  • Required Parameters

    title string required

    Title of the document, in plain text.

    MinLength: 1   MaxLength: 250

    Optional Parameters

    content string

    The main content of the document, in one of the supported formats.

    Info

    • While this parameter is optional, it's used in nearly all cases as it holds the primary content of the document.

    • Supported formats: plaintext | html | markdown

    • Formats other than plain text will be converted to plain text before being processed and stored in the semantic index.

    • To use Gainly for searching files (such as PDFs, Microsoft Word docs, etc.) in your app, you must first convert the file content to one of the supported formats before including it in this field.

    MaxLength: 100 KB

    content_type string (enum)

    Content type of the content field. Default is plaintext.

    Valid values: plaintext | html | markdown

    created_at string

    ISO 8601 formatted string that indicates the creation time of the document.

    If not provided in the API request, it defaults to the timestamp when the document was added via the API.

    Example: 2023-10-05T14:48:02Z

    id string

    Unique ID for the document. If not specified, Gainly will automatically assign a unique ID.

    MinLength: 1   MaxLength: 128

    Allowed characters

    • The following characters are permitted:

      • Lowercase letters (a-z)
      • Uppercase letters (A-Z)
      • Numbers (0-9)
      • Underscore (_)
      • Hyphen (-)

    • This means you can use UUIDs, for example.

    language string (enum)

    Language code (of a supported language) that indicates the language of the document.

    Default is en.

    metadata object

    JSON object containing metadata related to the document.

    Info
    • metadata JSON can include arbitrary key-value pairs.
    • The values can themselves be objects, allowing for nested structures.
    • When performing a search, you can filter and sort by metadata values using dot notation.

    Max number of keys: 100

    MaxLength for a key: 50 characters

    MaxLength for a value: 500 characters

    source_uri string

    Source URI of the document. Typically a unique address/location/identifier (within your app) for the document.

    Info

    When a user clicks on a search result that corresponds to this document, you can use its source_uri to navigate the user to the correct location within your app.

    MaxLength: 1000

    tenant_id string required

    Tenant ID of the document owner.

    MinLength: 1   MaxLength: 250

    updated_at string

    ISO 8601 formatted string that indicates the last modification time of the document.

    If not provided in the API request, it defaults to the timestamp when the document was added via the API.

    Example: 2023-10-05T14:48:02Z

  • POST /v20241104/documents

    curl -X POST "https://api.gainly.ai/v20241104/documents" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \  # (1)!
  -d '{
    "title": "My awesome document",
    "content": "This document has great content. Can be really long, but is short here.",
    "source_uri": "/doc/7-my-awesome-document",
    "tenant_id": "tenant123"
  }'
    1. 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 add_document 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 DocumentAddResponse schema in the OpenAPI spec

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

var client = new HttpClient();

var payload = new {
    title = "My awesome document",
    content = "This document has great content. Can be really long, but is short here.",
    source_uri = "/doc/7-my-awesome-document",
    tenant_id = "tenant123"
};

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

var response = await client.PostAsJsonAsync(
    "https://api.gainly.ai/v20241104/documents",
    payload
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    package main

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

func main() {
    payload := `{
        "title": "My awesome document",
        "content": "This document has great content. Can be really long, but is short here.",
        "source_uri": "/doc/7-my-awesome-document",
        "tenant_id": "tenant123"
    }`

    req, _ := http.NewRequest("POST", "https://api.gainly.ai/v20241104/documents", strings.NewReader(payload))
    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)
}
    1. 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 payload = """
    {
        "title": "My awesome document",
        "content": "This document has great content. Can be really long, but is short here.",
        "source_uri": "/doc/7-my-awesome-document",
        "tenant_id": "tenant123"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gainly.ai/v20241104/documents"))
    .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());
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    // Node.js example using axios
const axios = require('axios');  // or: import axios from 'axios';

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

const payload = {
    title: 'My awesome document',
    content: 'This document has great content. Can be really long, but is short here.',
    source_uri: '/doc/7-my-awesome-document',
    tenant_id: 'tenant123'
};

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));
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    <?php

$client = new \GuzzleHttp\Client();

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

$response = $client->request('POST', $url, [
    'json' => [
        'title' => 'My awesome document',
        'content' => 'This document has great content. Can be really long, but is short here.',
        'source_uri' => '/doc/7-my-awesome-document',
        'tenant_id' => 'tenant123'
    ],
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
        'X-API-Key' => 'YOUR_API_KEY_HERE' # (1)!
    ],
]);

echo $response->getBody();
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    import requests

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

payload = {
    "title": "My awesome document",
    "content": "This document has great content. Can be really long, but is short here.",
    "source_uri": "/doc/7-my-awesome-document",
    "tenant_id": "tenant123"
}

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)
    1. 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/documents')

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 = {
    title: 'My awesome document',
    content: 'This document has great content. Can be really long, but is short here.',
    source_uri: '/doc/7-my-awesome-document',
    tenant_id: 'tenant123'
}.to_json

response = http.request(request)
puts response.read_body
    1. Replace YOUR_API_KEY_HERE with the value of your API key.

API Response

{
    "id": "PbOrIZIBzlg4zQqVFxxE",
    "object": "document",
    "title": "My awesome document",
    "content": "This document has great content. Can be really long, but is short here.",
    "metadata": null,
    "tenant_id": "tenant123",
    "language": "en",
    "source_uri": "/doc/7-my-awesome-document",
    "created_at": "2023-10-05T14:48:02Z",
    "updated_at": "2023-10-05T14:48:02Z",
    "token_usage": {
        "semantic_tokens": 8,  // determined by the size of 'title', 'content' fields
        "llm_tokens": {
            "llm_output_tokens": 0,
            "llm_input_tokens": 0,
            "model": null
        }
    },
    "livemode": false
}

Response will include the unique id assigned to the newly added document.