Grounded Responses API Reference

POST

grounded

responses

Grounded Responses API (v1)

curl --request POST \
  --url https://platform.ai.gloo.com/ai/v1/grounded/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "<string>",
  "model": "<string>",
  "certainty_threshold": 0.5,
  "frequency_penalty": 123,
  "image_generation": {},
  "instructions": "<string>",
  "max_output_tokens": 123,
  "parallel_tool_calls": true,
  "presence_penalty": 123,
  "prompt_cache_key": "<string>",
  "rag_publisher": "GlooGrounded",
  "reasoning": {},
  "response_format": {},
  "sources_limit": 3,
  "stop": null,
  "stream": false,
  "temperature": 123,
  "tool_choice": null,
  "tools": [
    {}
  ],
  "top_p": 123
}
'

import requests

url = "https://platform.ai.gloo.com/ai/v1/grounded/responses"

payload = {
    "input": "<string>",
    "model": "<string>",
    "certainty_threshold": 0.5,
    "frequency_penalty": 123,
    "image_generation": {},
    "instructions": "<string>",
    "max_output_tokens": 123,
    "parallel_tool_calls": True,
    "presence_penalty": 123,
    "prompt_cache_key": "<string>",
    "rag_publisher": "GlooGrounded",
    "reasoning": {},
    "response_format": {},
    "sources_limit": 3,
    "stop": None,
    "stream": False,
    "temperature": 123,
    "tool_choice": None,
    "tools": [{}],
    "top_p": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: '<string>',
    model: '<string>',
    certainty_threshold: 0.5,
    frequency_penalty: 123,
    image_generation: {},
    instructions: '<string>',
    max_output_tokens: 123,
    parallel_tool_calls: true,
    presence_penalty: 123,
    prompt_cache_key: '<string>',
    rag_publisher: 'GlooGrounded',
    reasoning: {},
    response_format: {},
    sources_limit: 3,
    stop: null,
    stream: false,
    temperature: 123,
    tool_choice: null,
    tools: [{}],
    top_p: 123
  })
};

fetch('https://platform.ai.gloo.com/ai/v1/grounded/responses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform.ai.gloo.com/ai/v1/grounded/responses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => '<string>',
    'model' => '<string>',
    'certainty_threshold' => 0.5,
    'frequency_penalty' => 123,
    'image_generation' => [
        
    ],
    'instructions' => '<string>',
    'max_output_tokens' => 123,
    'parallel_tool_calls' => true,
    'presence_penalty' => 123,
    'prompt_cache_key' => '<string>',
    'rag_publisher' => 'GlooGrounded',
    'reasoning' => [
        
    ],
    'response_format' => [
        
    ],
    'sources_limit' => 3,
    'stop' => null,
    'stream' => false,
    'temperature' => 123,
    'tool_choice' => null,
    'tools' => [
        [
                
        ]
    ],
    'top_p' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://platform.ai.gloo.com/ai/v1/grounded/responses"

	payload := strings.NewReader("{\n  \"input\": \"<string>\",\n  \"model\": \"<string>\",\n  \"certainty_threshold\": 0.5,\n  \"frequency_penalty\": 123,\n  \"image_generation\": {},\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"parallel_tool_calls\": true,\n  \"presence_penalty\": 123,\n  \"prompt_cache_key\": \"<string>\",\n  \"rag_publisher\": \"GlooGrounded\",\n  \"reasoning\": {},\n  \"response_format\": {},\n  \"sources_limit\": 3,\n  \"stop\": null,\n  \"stream\": false,\n  \"temperature\": 123,\n  \"tool_choice\": null,\n  \"tools\": [\n    {}\n  ],\n  \"top_p\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://platform.ai.gloo.com/ai/v1/grounded/responses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"<string>\",\n  \"model\": \"<string>\",\n  \"certainty_threshold\": 0.5,\n  \"frequency_penalty\": 123,\n  \"image_generation\": {},\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"parallel_tool_calls\": true,\n  \"presence_penalty\": 123,\n  \"prompt_cache_key\": \"<string>\",\n  \"rag_publisher\": \"GlooGrounded\",\n  \"reasoning\": {},\n  \"response_format\": {},\n  \"sources_limit\": 3,\n  \"stop\": null,\n  \"stream\": false,\n  \"temperature\": 123,\n  \"tool_choice\": null,\n  \"tools\": [\n    {}\n  ],\n  \"top_p\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://platform.ai.gloo.com/ai/v1/grounded/responses")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"<string>\",\n  \"model\": \"<string>\",\n  \"certainty_threshold\": 0.5,\n  \"frequency_penalty\": 123,\n  \"image_generation\": {},\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"parallel_tool_calls\": true,\n  \"presence_penalty\": 123,\n  \"prompt_cache_key\": \"<string>\",\n  \"rag_publisher\": \"GlooGrounded\",\n  \"reasoning\": {},\n  \"response_format\": {},\n  \"sources_limit\": 3,\n  \"stop\": null,\n  \"stream\": false,\n  \"temperature\": 123,\n  \"tool_choice\": null,\n  \"tools\": [\n    {}\n  ],\n  \"top_p\": 123\n}"

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

{
  "id": "resp_123",
  "object": "response",
  "created_at": 1716912000,
  "model": "gloo-openai-gpt-5.5",
  "status": "completed",
  "output": [
    {
      "type": "reasoning",
      "id": "rs_123",
      "summary": [
        {
          "type": "summary_text",
          "text": "The user is greeting me, so a short friendly reply fits."
        }
      ]
    },
    {
      "type": "message",
      "id": "msg_123",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help?"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 8,
    "output_tokens": 7,
    "total_tokens": 15
  },
  "reasoning": {
    "effort": "medium",
    "summary": "auto"
  }
}

Error Reference: Grounded Responses

Common errors: unsupported model, missing or invalid grounding parameters, context window exceeded, provider timeout, provider unavailable.

Authorizations

Authorization

string

header

default:<api-key>

required

Bearer authentication header of the form Bearer <api-key>, where <api-key> is your API key.

Headers

X-Cache-TTL

string | null

Body

application/json

Responses API request body extended with retrieval-augmented generation: retrieved publisher content is injected into the prompt before the model is called. Takes the same grounding parameters as the grounded Chat Completions endpoint.

input

required

String prompt or array of input items

model

string

required

certainty_threshold

number | null

Minimum vector-similarity certainty (0-1) a retrieved source must meet to be attached. Omit to use the server default.

Required range: 0 <= x <= 1

frequency_penalty

number | null

image_generation

Image Generation · object | null

Image generation options (quality, size) mapped onto OpenAI's image_generation tool; ignored by providers without quality controls.

instructions

string | null

max_output_tokens

integer | null

parallel_tool_calls

boolean | null

presence_penalty

number | null

prompt_cache_key

string | null

rag_publisher

string | null

default:GlooGrounded

Publisher whose content is searched for grounding sources. Omit the field to use the default publisher (GlooGrounded); send an empty string or null to disable retrieval and answer from the model alone.

reasoning

Reasoning Config · object | null

Reasoning controls for a Responses request. On the Responses endpoints, a summary comes back only when summary is set. See the Reasoning guide (/api-guides/reasoning).

Show child attributes

response_format

Response Format · object | null

sources_limit

integer

default:3

Maximum number of sources to retrieve and inject.

Required range: 1 <= x <= 10

stop

unknown

stream

boolean

default:false

temperature

number | null

tool_choice

unknown

tools

Tools · object[] | null

top_p

number | null

Response

Successful grounded Responses API result. If stream is false or omitted, the response is JSON and includes sources_returned. If stream=true, the response is a named Server-Sent Events stream and X-Sources-Returned reports whether retrieval returned sources.

A non-streaming grounded Responses API result.

string

required

object

string

default:response

required

Allowed value: "response"

created_at

integer

required

Unix timestamp when the response was created.

model

string

required

status

enum<string>

required

Available options:

completed,

failed,

in_progress,

incomplete

output

(Message · object | Image Generation · object | Function Call · object | Reasoning · object)[]

required

Items generated by the model, such as assistant messages, images, function calls, or reasoning summaries.

An assistant message produced by the model.

Message
Image Generation
Function Call
Reasoning

Show child attributes

sources_returned

boolean

required

Whether retrieval returned sources used to ground the request.

usage

Usage · object

Token usage for the response.

Show child attributes

instructions

string

max_output_tokens

integer

metadata

object

Show child attributes

parallel_tool_calls

boolean

prompt_cache_key

string

reasoning

object

temperature

number

text

object

tool_choice

any

tools

object[]

top_p

number

ignored_params

Ignored Parameters · object

Parameters that were ignored or not applied as sent. The request still succeeds. Entries are name=value: sampling parameters the selected model does not accept and, on Direct Responses, reasoning removed from input (input.reasoning=<n> reasoning items, input.reasoning_paired=<n> other items removed with them) and stateful parameters that have no effect (previous_response_id, conversation, store=True, background=True). On a stream, the parameter names are in the X-Ignored-Params header instead.

Show child attributes

Example:

{
  "params": ["input.reasoning=1"],
  "model": "gloo-openai-gpt-5.4-nano",
  "reason": "These parameters were ignored and did not affect the response: the model does not accept them, or this surface does not forward them to the provider."
}

reasoning_carryover

Reasoning Carry-over Report · object

What happened to the reasoning items in the request's input. Present only when input contained at least one reasoning item, or the request asked for include: ["reasoning.encrypted_content"]; otherwise absent. Gloo does not carry reasoning from one request to the next: reasoning state sent back in input is removed before any model is called, and the request still succeeds. Returned by the guarded Responses and Grounded Responses endpoints. On a stream, the counts are in the X-Gloo-Reasoning-Carryover header and this object is a top-level field of the final response.completed or response.incomplete event's data; a stream that fails before either event ends without it. Direct Responses does not return this object or the header: it reports removed reasoning as input.reasoning=<n> and input.reasoning_paired=<n> in ignored_params (X-Ignored-Params on a stream).

Show child attributes

Example:

{
  "received": 1,
  "carried": 0,
  "dropped": [
    {
      "id": "rs_123",
      "reason": "not_gloo_state"
    }
  ],
  "not_sealed": null,
  "paired_removed": 1
}

⌘I

Grounded Responses API (v1)

curl --request POST \
  --url https://platform.ai.gloo.com/ai/v1/grounded/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "<string>",
  "model": "<string>",
  "certainty_threshold": 0.5,
  "frequency_penalty": 123,
  "image_generation": {},
  "instructions": "<string>",
  "max_output_tokens": 123,
  "parallel_tool_calls": true,
  "presence_penalty": 123,
  "prompt_cache_key": "<string>",
  "rag_publisher": "GlooGrounded",
  "reasoning": {},
  "response_format": {},
  "sources_limit": 3,
  "stop": null,
  "stream": false,
  "temperature": 123,
  "tool_choice": null,
  "tools": [
    {}
  ],
  "top_p": 123
}
'

import requests

url = "https://platform.ai.gloo.com/ai/v1/grounded/responses"

payload = {
    "input": "<string>",
    "model": "<string>",
    "certainty_threshold": 0.5,
    "frequency_penalty": 123,
    "image_generation": {},
    "instructions": "<string>",
    "max_output_tokens": 123,
    "parallel_tool_calls": True,
    "presence_penalty": 123,
    "prompt_cache_key": "<string>",
    "rag_publisher": "GlooGrounded",
    "reasoning": {},
    "response_format": {},
    "sources_limit": 3,
    "stop": None,
    "stream": False,
    "temperature": 123,
    "tool_choice": None,
    "tools": [{}],
    "top_p": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: '<string>',
    model: '<string>',
    certainty_threshold: 0.5,
    frequency_penalty: 123,
    image_generation: {},
    instructions: '<string>',
    max_output_tokens: 123,
    parallel_tool_calls: true,
    presence_penalty: 123,
    prompt_cache_key: '<string>',
    rag_publisher: 'GlooGrounded',
    reasoning: {},
    response_format: {},
    sources_limit: 3,
    stop: null,
    stream: false,
    temperature: 123,
    tool_choice: null,
    tools: [{}],
    top_p: 123
  })
};

fetch('https://platform.ai.gloo.com/ai/v1/grounded/responses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform.ai.gloo.com/ai/v1/grounded/responses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => '<string>',
    'model' => '<string>',
    'certainty_threshold' => 0.5,
    'frequency_penalty' => 123,
    'image_generation' => [
        
    ],
    'instructions' => '<string>',
    'max_output_tokens' => 123,
    'parallel_tool_calls' => true,
    'presence_penalty' => 123,
    'prompt_cache_key' => '<string>',
    'rag_publisher' => 'GlooGrounded',
    'reasoning' => [
        
    ],
    'response_format' => [
        
    ],
    'sources_limit' => 3,
    'stop' => null,
    'stream' => false,
    'temperature' => 123,
    'tool_choice' => null,
    'tools' => [
        [
                
        ]
    ],
    'top_p' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://platform.ai.gloo.com/ai/v1/grounded/responses"

	payload := strings.NewReader("{\n  \"input\": \"<string>\",\n  \"model\": \"<string>\",\n  \"certainty_threshold\": 0.5,\n  \"frequency_penalty\": 123,\n  \"image_generation\": {},\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"parallel_tool_calls\": true,\n  \"presence_penalty\": 123,\n  \"prompt_cache_key\": \"<string>\",\n  \"rag_publisher\": \"GlooGrounded\",\n  \"reasoning\": {},\n  \"response_format\": {},\n  \"sources_limit\": 3,\n  \"stop\": null,\n  \"stream\": false,\n  \"temperature\": 123,\n  \"tool_choice\": null,\n  \"tools\": [\n    {}\n  ],\n  \"top_p\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://platform.ai.gloo.com/ai/v1/grounded/responses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"<string>\",\n  \"model\": \"<string>\",\n  \"certainty_threshold\": 0.5,\n  \"frequency_penalty\": 123,\n  \"image_generation\": {},\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"parallel_tool_calls\": true,\n  \"presence_penalty\": 123,\n  \"prompt_cache_key\": \"<string>\",\n  \"rag_publisher\": \"GlooGrounded\",\n  \"reasoning\": {},\n  \"response_format\": {},\n  \"sources_limit\": 3,\n  \"stop\": null,\n  \"stream\": false,\n  \"temperature\": 123,\n  \"tool_choice\": null,\n  \"tools\": [\n    {}\n  ],\n  \"top_p\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://platform.ai.gloo.com/ai/v1/grounded/responses")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"<string>\",\n  \"model\": \"<string>\",\n  \"certainty_threshold\": 0.5,\n  \"frequency_penalty\": 123,\n  \"image_generation\": {},\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"parallel_tool_calls\": true,\n  \"presence_penalty\": 123,\n  \"prompt_cache_key\": \"<string>\",\n  \"rag_publisher\": \"GlooGrounded\",\n  \"reasoning\": {},\n  \"response_format\": {},\n  \"sources_limit\": 3,\n  \"stop\": null,\n  \"stream\": false,\n  \"temperature\": 123,\n  \"tool_choice\": null,\n  \"tools\": [\n    {}\n  ],\n  \"top_p\": 123\n}"

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

{
  "id": "resp_123",
  "object": "response",
  "created_at": 1716912000,
  "model": "gloo-openai-gpt-5.5",
  "status": "completed",
  "output": [
    {
      "type": "reasoning",
      "id": "rs_123",
      "summary": [
        {
          "type": "summary_text",
          "text": "The user is greeting me, so a short friendly reply fits."
        }
      ]
    },
    {
      "type": "message",
      "id": "msg_123",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help?"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 8,
    "output_tokens": 7,
    "total_tokens": 15
  },
  "reasoning": {
    "effort": "medium",
    "summary": "auto"
  }
}

General

Models

Responses & Completions

Embeddings

Content

Data Engine Content Controls

Legacy / Deprecated APIs

Grounded Responses API Reference

Error Reference: Grounded Responses

Authorizations

Headers

Body

Response