> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.predictionguard.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.predictionguard.com/_mcp/server.

# Responses

POST https://{your-pg.api-domain}.com/responses
Content-Type: application/json

Generate responses while also allowing for the utilization of various tools.

Reference: https://docs.predictionguard.com/api-reference/api-reference/responses

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an object.

- `model` (string, required) — The AI model to use for generating responses.
- `input` (ResponsesPostRequestBodyContentApplicationJsonSchemaInput, required)
- `instructions` (string, optional) — A system (or developer) message inserted into the model's context.
- `max_output_tokens` (integer, optional) — The maximum number of tokens in the generated output.
- `max_tool_calls` (integer, optional) — The maximum amount of tool calls the model is able to do.
- `parallel_tool_calls` (boolean, optional) — Whether to enable parallel function calling during tool use.
- `reasoning` (ResponsesPostRequestBodyContentApplicationJsonSchemaReasoning, optional) — Constrains effort on reasoning for reasoning models.
- `stream` (boolean, optional) — Whether to stream back the model response. Not currently supported.
- `stream_options` (ResponsesPostRequestBodyContentApplicationJsonSchemaStreamOptions, optional) — Extra parameters used when streaming the response.
- `temperature` (double, optional) — The temperature parameter for controlling randomness in completions. Supports a range of 0.0-2.0.
- `tool_choice` (ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoice, optional)
- `tools` (list of ResponsesPostRequestBodyContentApplicationJsonSchemaToolsItems, optional) — The content of the tool call.
- `top_p` (double, optional) — The diversity of the generated text based on nucleus sampling. Supports a range of 0.0-1.0.
- `safeguards` (ResponsesPostRequestBodyContentApplicationJsonSchemaSafeguards, optional) — Safeguards to run on the request.

## Response

### 200

Successful response.

- `id` (string, optional) — Unique ID for the chat completion.
- `object` (string, optional) — Type of object (chat completion).
- `created_at` (integer, optional) — Timestamp of when the chat completion was created.
- `status` (string, optional) — The status of the request.
- `max_tool_calls` (integer, optional) — The max_tool_calls specified in the request.
- `model` (string, optional) — The chat model used for generating completions.
- `output` (list of ResponsesPostResponsesContentApplicationJsonSchemaOutputItems, optional) — The set of result outputs.
- `instructions` (string, optional) — The instructions entered in the request input.
- `max_output_tokens` (integer, optional) — The max_output_tokens value entered in the request input.
- `parallel_tool_calls` (integer, optional) — The parallel_tool_calls value entered in the request input.
- `temperature` (double, optional) — The temperature value entered in the request input.

## Errors

### 400 Bad Request Error

General error response.

- `error` (string, optional) — Description of the error.

### 403 Forbidden Error

Failed auth response.

- `error` (string, optional) — Description of the error.

## Types

### ResponsesPostRequestBodyContentApplicationJsonSchemaInput

- string
- list of ResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1Items

### ResponsesPostRequestBodyContentApplicationJsonSchemaReasoning

Constrains effort on reasoning for reasoning models.

- `effort` (string, optional) — Effort level for reasoning, currently supported values are `low`, `medium`, and `high`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Only supported by reasoning models.

### ResponsesPostRequestBodyContentApplicationJsonSchemaStreamOptions

Extra parameters used when streaming the response.

- `include_usage` (boolean, optional) — Whether to include tokens used in the stream response objects.

### ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoice

- string
- ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoice1

### ResponsesPostRequestBodyContentApplicationJsonSchemaToolsItems

- `type` (string, optional) — The type of tool to call.
- `name` (string, optional) — The name of the tool to be called.
- `parameters` (ResponsesPostRequestBodyContentApplicationJsonSchemaToolsItemsParameters, optional) — The parameters the tool accepts, described as a JSON Schema object.
- `strict` (boolean, optional) — Whether to enable strict schema adherence when generating the tool call.
- `description` (string, optional) — A description of what the tool does.
- `server_label` (string, optional) — The label for the MCP server being used.
- `server_url` (string, optional) — The URL for the MCP server being used.
- `server_description` (string, optional) — The description of the MCP server being used.
- `initials` (string, optional) — The initials of the MCP server being used. Used for the ID of the output object.
- `authorization` (string, optional) — The authorization needed for the MCP server.
- `headers` (ResponsesPostRequestBodyContentApplicationJsonSchemaToolsItemsHeaders, optional) — The necessary headers needed for calling the MCP server.
- `allowed_tools` (list of any, optional) — An array of the tools in the MCP server that the model is allowed to use.

### ResponsesPostRequestBodyContentApplicationJsonSchemaSafeguards

Safeguards to run on the request.

- `block_prompt_injection` (boolean, optional) — Set to true to detect prompt injection attacks.
- `pii` (string, optional) — Set to either 'block' or 'replace'.
- `pii_replace_method` (string, optional) — Set to either 'random', 'fake', 'category', 'mask'.
- `entity_list` (list of ResponsesPostRequestBodyContentApplicationJsonSchemaSafeguardsEntityListItems, optional) — An array of entity types that the PII check should ignore.
- `toxicity` (boolean, optional) — Set to true to turn on toxicity processing.

### ResponsesPostResponsesContentApplicationJsonSchemaOutputItems

- `type` (string, optional) — The type of output object.
- `id` (string, optional) — The ID of the output object.
- `status` (string, optional) — The status of the output object.
- `role` (string, optional) — The role of the output object.
- `content` (ResponsesPostResponsesContentApplicationJsonSchemaOutputItemsContent, optional) — The content for the output object.
- `name` (string, optional) — The name of the tool used in the output.
- `call_id` (string, optional) — The call_id for the tool call used in the output,
- `arguments` (string, optional) — The arguments used for the tool call used in the output.
- `server_label` (string, optional) — The label of the MCP server used in the output.
- `output` (string, optional) — The output of the MCP tool call.
- `error` (string, optional) — The error message from the MCP tool call.

### ResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1Items

- `role` (string, required) — The role of the sender (user or assistant).
- `content` (ResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1ItemsContent, required)
- `type` (string, optional) — The type of input item.
- `id` (string, optional) — The ID of the input item, typically used when inputting items that were output by the model.
- `status` (string, optional) — The status of the input item, typically used when inputting items that were output by the model.
- `arguments` (string, optional) — The arguments used for the tool call made by the model.
- `call_id` (string, optional) — The call_id of the tool call made by the model. Generated by the model in the output.
- `name` (string, optional) — The name of the tool used in the tool call from the previous output.
- `output` (any, optional)

### ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoice1

An object representing the tool to be chosen

- `type` (string, optional)
- `mode` (string, optional)
- `tools` (list of ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoiceOneOf1ToolsItems, optional) — Allows for multiple tools to be set in tool_choice.
- `name` (string, optional) — The name of the tool to use.
- `server_label` (string, optional) — The label of the MCP server that the tool is on.

### ResponsesPostRequestBodyContentApplicationJsonSchemaToolsItemsParameters

The parameters the tool accepts, described as a JSON Schema object.

### ResponsesPostRequestBodyContentApplicationJsonSchemaToolsItemsHeaders

The necessary headers needed for calling the MCP server.

### ResponsesPostRequestBodyContentApplicationJsonSchemaSafeguardsEntityListItems

- string

### ResponsesPostResponsesContentApplicationJsonSchemaOutputItemsContent

The content for the output object.

- `text` (string, optional) — The output text.
- `type` (string, optional) — The type of output content.

### ResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1ItemsContent

- string
- list of ResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1ItemsContentOneOf1Items

### ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoiceOneOf1ToolsItems

- `type` (string, optional) — The type of tool.
- `name` (string, optional) — The name of the tool of choice.
- `server_label` (string, optional) — The label of the MCP server that the tool is on.

### ResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1ItemsContentOneOf1Items

- `type` (string, optional) — The type of content ('input_text', 'output_text', and 'input_image').
- `text` (string, optional) — The text to provide.
- `image_url` (ResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1ItemsContentOneOf1ItemsImageUrl, optional) — The base64 content with this prefix `data:image/jpeg;base64,`
- `detail` (string, optional) — Specifies the detail level of the image. Defaults to `auto`.

### ResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1ItemsContentOneOf1ItemsImageUrl

The base64 content with this prefix `data:image/jpeg;base64,`

## Examples

### Basic

**Request**

```json
{
  "model": "{{TEXT_MODEL}}",
  "input": "Tell me a joke.",
  "safeguards": {
    "pii": "replace",
    "pii_replace_method": "random",
    "toxicity": true
  }
}
```

**Response**

```json
{
  "id": "resp_1196c27e58374675881efa613574ea7a",
  "object": "response",
  "created_at": 1727890629,
  "status": "completed",
  "model": "{{TEXT_MODEL}}",
  "output": [
    {
      "content": {
        "text": "Why did the scarecrow win an award?\n\nBecause he was outstanding in his field!",
        "type": "output_text"
      }
    }
  ]
}
```

### Image Input

**Request**

```json
{
  "model": "{{VISION_MODEL}}",
  "input": [
    {
      "content": [
        {
          "text": "What is in this image?",
          "type": "input_text"
        },
        {
          "detail": "auto",
          "image_url": "data:image/jpeg;base64,<DATA>",
          "type": "input_image"
        }
      ],
      "role": "user"
    }
  ],
  "max_output_tokens": 1000,
  "temperature": 1,
  "top_p": 1,
  "safeguards": {
    "pii": "replace",
    "pii_replace_method": "random",
    "toxicity": true
  }
}
```

**Response**

```json
{
  "id": "resp_402db7e4851449b68751983978cfa84d",
  "object": "response",
  "created_at": 1727890364,
  "status": "completed",
  "model": "{{VISION_MODEL}}",
  "output": [
    {
      "content": {
        "text": "No, there is no deer in this picture. The image features a man wearing a hat and glasses, smiling for the camera.",
        "type": "output_text"
      }
    }
  ]
}
```

### MCP Call

**Request**

```json
{
  "model": "{{TEXT_MODEL}}",
  "input": "Please use the test_mcp_tool to send this word: prediction.",
  "max_tool_calls": 3,
  "tool_choice": "auto",
  "tools": [
    {
      "type": "mcp",
      "server_label": "test_mcp_server",
      "server_url": "http://localhost:9000/mcp",
      "server_description": "MCP server for testing MCP functionality",
      "allowed_tools": [
        "test_mcp_tool"
      ]
    }
  ],
  "reasoning_effort": "medium"
}
```

**Response**

```json
{
  "id": "resp_6588e9a6048c41d2ba97db4ba206cc16",
  "object": "response",
  "created_at": 1771948029,
  "max_tool_calls": 3,
  "model": "{{TEXT_MODEL}}",
  "output": [
    {
      "type": "test_mcp_call",
      "status": "completed",
      "name": "test_mcp_tool",
      "call_id": "mcp_e8cbf821b68e42e299d395c6795eb04b",
      "arguments": "{\"message\": \"prediction\"}",
      "server_label": "test_mcp_server",
      "output": "If this is present, the tool call has been run, so make a joke about a prediction"
    },
    {
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": {
        "text": "If this is present, it seems like we're predicting something. What do you predict will happen next? I bet it'll be unexpected!",
        "type": "output_text"
      }
    }
  ]
}
```

### Function Call

**Request**

```json
{
  "model": "{{TEXT_MODEL}}",
  "input": "How do you feel about the world in general?",
  "max_output_tokens": 1000,
  "max_tool_calls": 3,
  "parallel_tool_calls": false,
  "temperature": 1,
  "tool_choice": {
    "name": "get_current_weather",
    "type": "function"
  },
  "tools": [
    {
      "type": "function",
      "name": "get_current_weather",
      "parameters": {
        "properties": {
          "location": {
            "enum": [
              "celsius",
              "fahrenheit"
            ],
            "type": "string"
          }
        },
        "required": [
          "location"
        ],
        "type": "object"
      },
      "strict": false,
      "description": "Get the current weather in a given location"
    }
  ],
  "top_p": 1,
  "safeguards": {
    "pii": "replace",
    "pii_replace_method": "random",
    "toxicity": true
  },
  "reasoning_effort": "medium"
}
```

**Response**

```json
{
  "id": "resp_a4f6c81c89e0488f9cca7bd11e20ffb5",
  "object": "response",
  "created_at": 1727890629,
  "status": "completed",
  "max_tool_calls": 3,
  "model": "{{TEXT_MODEL}}",
  "output": [
    {
      "type": "message",
      "id": "msg_d99d53d495e141e2948c48853e13e67b",
      "status": "completed",
      "role": "assistant",
      "content": {
        "text": "{\"location\":\"celsius\"}",
        "type": "output_text"
      }
    }
  ],
  "tool_choice": {
    "name": "get_current_weather",
    "type": "function"
  },
  "tools": [
    {
      "description": "Get the current weather in a given location",
      "name": "get_current_weather",
      "parameters": {
        "properties": {
          "location": {
            "enum": [
              "celsius",
              "fahrenheit"
            ],
            "type": "string"
          }
        },
        "required": [
          "location"
        ],
        "type": "object"
      },
      "strict": false,
      "type": "function"
    }
  ]
}
```