Create a prompt

Updated: November 12, 2026

POST/genai/{connection_id}/prompt

Creates a GenaiPrompt. Provide the unified GenaiPrompt fields in the request body; they are mapped to the provider's API. Returns the created GenaiPrompt.

Parameters

Payload

model_idstring

The ID of the model to use (a GenaiModel ID)

messages array

The conversation to send to the model, in order; each message has a role and its content

temperaturenumber

0-1

max_tokensnumber

a float between 0-1

responsesstring array

tokens_usednumber

mcp_urlstring

Supply a remote MCP URL to send to the LLM API for it to call its tools. Note: Some LLM APIs do not yet support remote MCP URLs.

mcp_deferred_toolsstring array

mcp_authorization_tokenstring

OAuth Bearer token for MCP servers that require authentication.

questions array

Typed questions to evaluate against the messages (for decision models such as TypeSafe Jev).

answers array

One answer per question, matched by id.

skill_idsstring array

ids of the genai_skill objects (Agent Skills) to make available to the LLM while it answers.

raw

Returns

GenaiPrompt

Response field	Type	Required	Description
`model_id`	string	No	The ID of the model to use (a GenaiModel ID)
`messages`	GenaiContent[]	No	The conversation to send to the model, in order; each message has a role and its content
`messages[].role`	enum	No	Values: `SYSTEM`, `USER`, `ASSISTANT`
`messages[].content`	string	Yes
`messages[].images`	string[]	No	Images for the model to evaluate with this message, as base64 data URLs (data:image/png;base64,...). Only for models with has_vision.
`temperature`	number	No	0-1
`max_tokens`	number	No	a float between 0-1
`responses`	string[]	No
`tokens_used`	number	No
`mcp_url`	string	No	Supply a remote MCP URL to send to the LLM API for it to call its tools. Note: Some LLM APIs do not yet support remote MCP URLs.
`mcp_deferred_tools`	string[]	No
`mcp_authorization_token`	string	No	OAuth Bearer token for MCP servers that require authentication.
`questions`	GenaiQuestion[]	No	Typed questions to evaluate against the messages (for decision models such as TypeSafe Jev).
`questions[].id`	string	Yes	A caller-chosen key; the matching answer is returned with the same id.
`questions[].type`	enum	Yes	Values: `BOOLEAN`, `CHOICE`, `SCORE`
`questions[].instructions`	string	Yes	The question to evaluate.
`questions[].options`	string[]	No	CHOICE: the options to select from; SCORE: the ordered levels (lowest first).
`answers`	GenaiAnswer[]	No	One answer per question, matched by id.
`answers[].id`	string	Yes	The id of the genai_prompt question that this answers.
`answers[].type`	enum	Yes	Values: `BOOLEAN`, `CHOICE`, `SCORE`
`answers[].value`	string	No	CHOICE: the selected option.
`answers[].score`	number	No	SCORE: the probability-weighted level index; BOOLEAN: the probability (0-1) that the answer is yes.
`answers[].probabilities`	GenaiAnswerProbability[]	No	CHOICE/SCORE: the probability of every option or level.
`answers[].probabilities[].option`	string	Yes	CHOICE: the option; SCORE: the level description.
`answers[].probabilities[].probability`	number	Yes	0-1
`answers[].confidence`	number	No	0-1: how certain the model is of the answer.
`skill_ids`	string[]	No	ids of the genai_skill objects (Agent Skills) to make available to the LLM while it answers.

Errors

Errors return the HTTP status code and a JSON body with statusCode, error (the short label) and message (a human-readable detail).

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests to unified.to API; max requests per minute: N"
}

Status	Error	Meaning
`400`	Bad Request	The request was malformed or failed validation.
`401`	Unauthorized	The connection is likely broken; re-authorize it.
`403`	Forbidden	The connection is missing permissions or scopes.
`404`	Not Found	The requested resource does not exist.
`429`	Too Many Requests	Rate limit exceeded (see the two sources below).
`500`	Internal Server Error	An unexpected error occurred.
`501`	Not Implemented	Not supported by this integration.

Errors from the underlying integration pass through: the integration's status comes back as ours (429, 401, 403, 404 or 5xx), usually with its message. When the integration's error body is unclear, Unified extracts what it can and returns a clearer message.

429 Too Many Requests

A 429 has two possible sources:

The integration's own rate limit, passed through.
Unified's workspace limit: a rolling 60 seconds, set by plan, with the message Too many requests to unified.to API; max requests per minute: N.

const options = {
  method: 'POST',
  url: 'https://api.unified.to/genai/5de520f96e439b002043d8dc/prompt',
  headers: {
    authorization: 'bearer .....'
  },
  data: undefined,
  params: {
    fields: '',
    raw: '',
  }
};

const results = await axios.request(options);

Code Samples

Node.js SDK

import { UnifiedTo } from '@unified-api/typescript-sdk';

const sdk = new UnifiedTo({
    security: {
        jwt: '<YOUR_API_KEY_HERE>',
    },
});

const connectionId = '5de520f96e439b002043d8dc';

const results = await sdk.genai.createGenaiPrompt({ connectionId, genaiPrompt: { }, 
    fields: '',
    raw: '',
 });

Node.js (axios)

const options = {
  method: 'POST',
  url: 'https://api.unified.to/genai/5de520f96e439b002043d8dc/prompt',
  headers: {
    authorization: 'bearer .....'
  },
  data: undefined,
  params: {
    fields: '',
    raw: '',
  }
};

const results = await axios.request(options);

Java

AsyncHttpClient client = new DefaultAsyncHttpClient();

client.prepare("POST", "https://api.unified.to/genai/5de520f96e439b002043d8dc/prompt?fields=&raw=")
  .setHeader("accept", "application/json")
  .setHeader("authorization", ".....")
  .execute()
  .toCompletableFuture()
  .thenAccept(System.out::println)
  .join();

client.close();

Go

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

url := `https://api.unified.to/genai/5de520f96e439b002043d8dc/prompt?fields=&raw=

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

req.Header.Add("accept", "application/json")
req.Header.Add("authorization", ".....")

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

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

Python

import requests

url = "https://api.unified.to/genai/5de520f96e439b002043d8dc/prompt?fields=&raw="

headers = {
    "accept": "application/json",
    "authorization": "....."
}

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

PHP

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unified.to/genai/5de520f96e439b002043d8dc/prompt?fields=&raw=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "accept: application/json",
    "authorization: ....."
  ],
]);

Ruby

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

url = URI("https://api.unified.to/genai/5de520f96e439b002043d8dc/prompt?fields=&raw=")

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

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = '....'

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

cURL

curl --request POST \
  --url 'https://api.unified.to/genai/5de520f96e439b002043d8dc/prompt?fields=&raw=' \
  --header 'accept: application/json' \
  --header 'authorization: .....'

Are we missing anything? Let us know

Was this page helpful?