Retrieve Metadata Schema

Retrieve the automatically-inferred schema of your document metadata.

How is the metadata schema created?

This schema is automatically created as you submit arbitrary key-value pairs through the metadata parameter in Add document or Update document API requests. Refer to best practices for tips.

Endpoint¶

GET /v20241104/documents/metadata-schema

API Request¶

Parameters

No parameters.

GET /v20241104/documents/metadata-schema

cURLAI PromptC#GoJavaNode.jsPHPPythonRuby

curl "https://api.gainly.ai/v20241104/documents/metadata-schema" \
  -H "X-API-Key: YOUR_API_KEY_HERE"  # (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 retrieve_metadata_schema 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 MetadataSchemaResponse schema in the OpenAPI spec
6. Use the schema information to understand the available metadata fields and their types as described in the docs: https://docs.gainly.ai/latest/docs/metadata/

using System.Net.Http;

var client = new HttpClient();

var url = "https://api.gainly.ai/v20241104/documents/metadata-schema";

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

var response = await client.GetAsync(url);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Replace YOUR_API_KEY_HERE with the value of your API key.

package main

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

func main() {
    url := "https://api.gainly.ai/v20241104/documents/metadata-schema"

    req, _ := http.NewRequest("GET", url, nil)
    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/documents/metadata-schema";

var request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("X-API-Key", "YOUR_API_KEY_HERE") // (1)!
    .GET()
    .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/documents/metadata-schema';

const headers = {
    'X-API-Key': 'YOUR_API_KEY_HERE' // (1)!
};

axios.get(url, { 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/documents/metadata-schema';

$response = $client->request('GET', $url, [
    'headers' => [
        '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/documents/metadata-schema"

headers = {
    "X-API-Key": "YOUR_API_KEY_HERE" # (1)!
}

response = requests.get(url, 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/documents/metadata-schema')

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

request = Net::HTTP::Get.new(url)
request['X-API-Key'] = 'YOUR_API_KEY_HERE' # (1)!

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

Replace YOUR_API_KEY_HERE with the value of your API key.

API Response¶

Example input¶

Let's say you added a document with the following metadata parameter:

"metadata": {
    "color": "red",
    "is_sale": true,
    "length": 52,
    "location_geo_point": {
        "lat": 45.67,
        "lon": -111.04
    },
    "price": 99.99,
    "released_on": "2024-01-01T00:00:00.000Z",
    "sale": {
        "sale_price": 79.99,
        "sale_starts": "2024-09-01T00:00:00.000Z",
        "sale_ends": "2024-10-01T00:00:00.000Z"
    },
    "tags": ["shirt", "clothing"]
}

Example API response¶

For this example, Retrieve metadata schema API response would be as follows:

{
    "object": "metadata_schema_result",
    "url": "/v20241104/documents/metadata-schema",
    "livemode": false,
    "metadata": {
        "properties": {
            "color": {
              "type": "keyword"
            },
            "is_sale": {
              "type": "boolean"
            },
            "length": {
              "type": "integer"
            },
            "location_geo_point": {
              "type": "geo_point"
            },
            "price": {
              "type": "float"
            },
            "released_on": {
              "type": "date",
              "format": "strict_date_optional_time"
            },
            "sale": {
              "properties": {
                "sale_ends": {
                  "type": "date",
                  "format": "strict_date_optional_time"
                },
                "sale_price": {
                  "type": "float"
                },
                "sale_starts": {
                  "type": "date",
                  "format": "strict_date_optional_time"
                }
              }
            },
            "tags": {
              "type": "keyword"
            }
        }
    }
}

Strings¶

Strings are stored as the keyword field type, meaning the field is not indexed for full-text search. Instead, it is used for filtering, sorting, and faceting. See color in the example above.

Arrays¶

Arrays are represented by the field type of an individual element within that array. See tags in the example above.

Empty API Response¶

If you haven't added any documents that contain the metadata parameter, API response will be as follows:

{
    "object": "metadata_schema_result",
    "url": "/v20241104/documents/metadata-schema",
    "metadata": {}
}