All Collections
Advanced Features
PromptHub API Documentation
PromptHub API Documentation

PromptHub API Reference

Dalton Pierce avatar
Written by Dalton Pierce
Updated over a week ago

PromptHub API

PromptHub offers a simple REST API to interact with your prompts from your own application. Features offered by our API will continue to grow and improve over time with the help of your feedback.
โ€‹

Endpoints


Getting Your Project's "Head"

Your Project "head" refers to your last committed prompt. Forms and our Running Your Project's "Head" Prompt endpoint both use your Project's "head" to execute LLM requests.

Gets your "head" prompt for a given project. Useful for making LLM requests from your application's backend using your PromptHub prompts.

GET https://app.prompthub.us/api/v1/projects/{id}/head

Throttling

Requests to this endpoint are throttled to 30 requests per minute.

Request

Endpoint

Parameter

Value

https://app.prompthub.us/api/v1/projects/{id}/head

The ID of a given project, can be found in your browser's URL bar when viewing that project.

Headers

Header

Value

Notes

Authorization

Bearer {token}

Generate your API Token and replace {token} in the Authorization header.

Accept

application/json

Required to properly format error responses.

Content-Type

application/json

Optional.

Examples

cURL

curl --location 'https://app.prompthub.us/api/v1/projects/{id}/head' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

PHP

$url = 'https://app.prompthub.us/api/v1/projects/{id}/head';
$headers = [
'Authorization: Bearer {token}'
'Accept: application/json',
'Content-Type: application/json',
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

Python

import requests

url = 'https://app.prompthub.us/api/v1/projects/{id}/head'
headers = {
'Authorization': 'Bearer {token}'
'Accept': 'application/json',
'Content-Type': 'application/json'
}

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

print(response.text)

Responses

200 - OK

Be sure to replace the variable syntax used in your prompt and system message with contextual data from your application.

{
"data": {
"provider": "OpenAI",
"model": "gpt-3.5-turbo",
"system_message": "Respond like your a {{ tone }}",
"prompt": "Write a {{ type }} about {{ subject }}",
"formatted_request": {
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "system",
"content": "Respond like your a {{ tone }}"
},
{
"role": "user",
"content": "Write a {{ type }} about {{ subject }}"
}
],
"max_tokens": 4096,
"temperature": 0.5,
"top_p": 1,
"presence_penalty": 0,
"frequency_penalty": 0
},
"commit_title": "Improved Prompt",
"commit_description": "Added tone to system message",
"variables": {
"system_message": [
"tone"
],
"prompt": [
"type",
"subject"
],
},
"project": {
"name": "Test Prompt"
},
"branch": {
"name": "master"
},
"configuration": {
"max_tokens": 4096,
"temperature": 0.5,
"top_p": 1,
"top_k": null,
"presence_penalty": 0,
"frequency_penalty": 0,
}
},
"status": "OK",
"code": 200
}

401 - Unauthorized

Your request is missing a valid API Token. Be sure to generate one on the API Tokens page with proper permissions. Make sure the token is properly included as a bearer token in the Authorization header of your request.

{
"status": "error",
"code": 401,
"message": "Unauthorized. Check your API Token."
}

403 - Forbidden

Your API Token is missing the proper permission to use this API endpoint. Navigate to the API Tokens page, click "Permissions" next to your token and check run:project and/or get:project .

{
"status": "error",
"code": 403,
"message": "Your API Token cannot perform this action. Check your token permissions."
}

404 - Not Found

The Project ID you provided couldn't be found, or your API Token does not grant access to it. Double check the Project ID you used.

{
"status": "error",
"code": 404,
"message": "Project {id} not found. Check your Project ID."
}

422 - Unproccessable Entity

Your missing a prerequisite to use this endpoint. Make sure you've entered proper API Keys for your desired LLM provider(s).

{
"status": "error",
"code": 422,
"message": "{provider} API Key required for Project {id} or associated Team."
}

429 - Too Many Requests

You're making requests too quickly and have been throttled. We allow up to 30 requests per minute for this endpoint.

{
"status": "throttled",
"code": 429,
"message": "Too many requests. Please wait {n} seconds."
}

500 - Server Error

Something went wrong on our end. Let us know if the problem persists.

{
"status": "error",
"code": 500,
"message": "An unexpected error has occurred."
}

Injecting Your Data

This endpoint returns a formatted_request object with which you can make requests to your LLM provider. But first, you have to replace the variable placeholders with data from your own application's context.

Here's are some example of replacing `{{ variable }}` placeholders with your own data.

Find and Replace Variable Placeholders

// Given an object with the following shape:
$variables = [
'variable_1' => 'Variable 1 Value',
'variable_2' => 'Variable 2 Value',
// ...
]

$variableRegex = "/\{\{\s*([a-zA-Z0-9_-]+)\s*}}/";

$formattedPrompt = preg_replace_callback(
$variableRegex,
fn ($matches) => $variables[$matches[1]] ?? $matches[0],
$rawPrompt
);


Running Your Project's "Head"

Run the "head" prompt version for the target Project.

POST https://app.prompthub.us/api/v1/projects/{id}/run

Throttling

Requests to this endpoint are throttled to 1000 requests per token per minute, and 20 requests per session per minute.

Request

Endpoint

Parameter

Value

https://app.prompthub.us/api/v1/projects/{id}/run

The ID of a given project, can be found in your browser's URL bar when viewing that project.

Headers

Header

Value

Notes

Authorization

Bearer {token}

Generate your API Token and replace {token} in the Authorization header.

Accept

application/json

Required to properly format error responses.

Content-Type

application/json

Optional.

Body

Field

Value

Notes

metadata

{ 
"user_id": $id,
"user_email": $email,
"user_name": $name,
"user_avatar": $avatar,
// ... Any other fields
}

Pass information about the authenticated user in your context to PromptHub logs.
โ€‹

variables

{ 
"variable_1": $variable1,
"variable_2": $variable2
// ...
}

Define your variable values in your application's context.

Examples

cURL

 curl --location https://app.prompthub.us/api/v1/projects/{id}/run \
-X POST \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"user_id": 42,
"user_email": "doug@fourty-two.rocks",
"user_name": "Douglas Adams",
"user_avatar": "https://assets.prompthub.us/image/42",
"other_useful_info": true
},
"variables": {
"variable_1": "Guide",
"variable_2": "Galaxies"
}
}'

PHP

$url = 'https://app.prompthub.us/api/v1/projects/{id}/run';
$headers = [
'Authorization: Bearer {token}'
'Accept: application/json',
'Content-Type: application/json',
];
$data = json_encode([
'metadata' => [
'user_id' => 42,
'user_email' => 'doug@fourty-two.rocks',
'user_name' => 'Douglas Adams',
'user_avatar' => 'https://assets.prompthub.us/image/42',
'other_userful_info' => true
],
'variables' => [
'variable_1' => 'Guide',
'variable_2' => 'Galaxies'
]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

Python

import requests

url = 'https://app.prompthub.us/api/v1/projects/{id}/run'
headers = {
'Authorization': 'Bearer {token}'
'Accept': 'application/json',
'Content-Type': 'application/json',
}
data = {
'metadata': {
'user_id': 42,
'user_email': 'doug@fourty-two.rocks',
'user_name': 'Douglas Adams',
'user_avatar': 'https://assets.prompthub.us/image/42',
},
'variables': {
'variable_1': 'Guide',
'variable_2': 'Galaxies'
}
}

res = requests.post(url, headers=headers, json=data)
print(res.json())

Responses

200 - OK

{
"data": {
"id": 4401,
"project_id": 60,
"transaction_id": 4532,
"previous_output_id": null,
"provider": "OpenAI",
"model": "gpt-3.5-turbo-0613",
"prompt_tokens": 18,
"completion_tokens": 42,
"total_tokens": 60,
"finish_reason": "stop",
"text": "The answer to life, the universe, and everything is... 42.",
"cost": 0.000995,
"latency": 3132.01,
"network_time": 226.42,
"total_time": 3358.43
},
"status": "OK",
"code": 200
}

401 - Unauthorized

Your request is missing a valid API Token. Be sure to generate one on the API Tokens page with proper permissions. Make sure the token is properly included as a bearer token in the Authorization header of your request.

{
"status": "error",
"code": 401,
"message": "Unauthorized. Check your API Token."
}

403 - Forbidden

Your API Token is missing the proper permission to use this API endpoint. Navigate to the API Tokens page, click "Permissions" next to your token and check run:project and/or get:project .

{
"status": "error",
"code": 403,
"message": "Your API Token cannot perform this action. Check your token permissions."
}

404 - Not Found

The Project ID you provided couldn't be found, or your API Token does not grant access to it. Double check the Project ID you used.

{
"status": "error",
"code": 404,
"message": "Project {id} not found. Check your Project ID."
}

422 - Unproccessable Entity

Your missing a prerequisite to use this endpoint. Make sure you've entered proper API Keys for your desired LLM provider(s).

{
"status": "error",
"code": 422,
"message": "{provider} API Key required for Project {id} or associated Team."
}

429 - Too Many Requests

You're making requests too quickly and have been throttled. We allow up to 30 requests per minute for this endpoint.

{
"status": "throttled",
"code": 429,
"message": "Too many requests. Please wait {n} seconds."
}

500 - Internal Server Error

Something went wrong on our end. Let us know if the problem persists.

{
"status": "error",
"code": 500,
"message": "An unexpected error has occurred."
}

Did this answer your question?