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 Authenticated User
Returns basic information about the currently authenticated user. Can be useful for validating API Tokens and finding Team and Project/Prompt ID's.
GET https://app.prompthub.us/api/v1/me
Throttling
Requests to this endpoint are throttled to 10 requests per token per minute.
Request
Headers
Header | Value | Notes |
|
| Generate your API Token and replace |
|
| Required to properly format error responses. |
|
| Optional. |
Examples
cURL
curl --location 'https://app.prompthub.us/api/v1/me' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
PHP
$url = 'https://app.prompthub.us/api/v1/me';
$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/me'
headers = {
'Authorization': 'Bearer {token}'
'Accept': 'application/json',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.text)
Responses
200 - OK
{
"data": {
"id": 6,
"current_team_id": 1,
"current_project_id": 1,
"current_prompt_id": 13,
"name": "John Smith",
"email": "john@prompthub.us",
"avatar": "https://ui-avatars.com/api?name=JS&color=27187e&background=f1effa",
"created_at": "2024-01-01T23:05:57+00:00",
"current_team": {
"id": 1,
"user_id": 1,
"name": "PromptHub"
}
},
"status": "OK",
"code": 200
}
401 - Unauthenticated
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.
{
"message": "Unauthenticated."
}
429 - Too Many Requests
You're making requests too quickly and have been throttled. We allow up to 10 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."
}
Getting Your Team's Prompts
Returns a list of all your team's prompts. Includes information about each prompt's "head", relevant groups, variables, etc.
You can find your Team ID by visiting your Team Settings and copying the number at the end of the URL. Alternatively, once you set-up your API key try hitting our api/v1/me
endpoint and use your current_team_id
.
GET https://app.prompthub.us/api/v1/teams/{id}/projects
Throttling
Requests to this endpoint are throttled to 10 requests per token per minute.
Request
Endpoint
Parameter | Value |
| The ID of a given team, can be found in your browser's URL bar when viewing your "Team Settings" |
Headers
Header | Value | Notes |
|
| Generate your API Token and replace |
|
| Required to properly format error responses. |
|
| Optional. |
Examples
cURL
curl --location 'https://app.prompthub.us/api/v1/teams/{id}/projects' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
PHP
$url = 'https://app.prompthub.us/api/v1/teams/{id}/projects';
$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/teams/{id}/projects'
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": [
{
"id": 1,
"name": "fugit ducimus",
"description": "Sed quam aut et velit temporibus. Qui nemo libero labore facere. Expedita reprehenderit perferendis voluptates dolores quia quas.",
"head": {
"id": 7,
"project_id": 1,
"user_id": 6,
"provider": "Anthropic",
"model": "claude-2",
"prompt": "Ping",
"system_message": "Return Pong",
"formatted_request": {
"model": "claude-2",
"prompt": "Return Pong\n\n\nHuman: Ping\n\nAssistant:",
"max_tokens_to_sample": 200000,
"temperature": 0.5,
"top_p": 1,
"stream": false
},
"hash": "c97081db",
"commit_title": "Test",
"commit_description": "test",
"prompt_tokens": 5,
"system_message_tokens": 3,
"committed": true,
"created_at": "2024-03-04T16:21:02+00:00",
"updated_at": "2024-03-04T20:25:24+00:00",
"variables": {
"system_message": [],
"prompt": [
"test"
]
},
"branch": {
"id": 1,
"name": "master"
},
"configuration": {
"id": 5,
"max_tokens": 200000,
"temperature": 0.5,
"top_p": 1,
"top_k": null,
"presence_penalty": 0,
"frequency_penalty": 0,
"stop_sequences": null
}
},
"groups": [
{
"id": 1,
"name": "Test Group",
"description": "Test"
}
]
},
{
"id": 2,
"name": "ipsam ipsum",
"description": "Saepe tempore et aut est ut inventore sit. Voluptas molestias autem qui excepturi ut qui. Dolor veniam labore reprehenderit eaque aut. Repudiandae incidunt optio ullam sit.",
"head": null,
"groups": []
}
],
"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 get:project
.
{
"status": "error",
"code": 403,
"message": "Your API Token cannot perform this action. Check your token permissions."
}
404 - Not Found
The Team ID you provided couldn't be found, or your API Token does not grant access to it. Double check the Team ID you used.
{
"status": "error",
"code": 404,
"message": "Team {id} not found. Check your Team ID."
}
429 - Too Many Requests
You're making requests too quickly and have been throttled. We allow up to 10 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."
}
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 |
| The ID of a given project, can be found in your browser's URL bar when viewing that project. |
Headers
Header | Value | Notes |
|
| Generate your API Token and replace |
|
| Required to properly format error responses. |
|
| 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": {
"id": 1885,
"project_id": 60,
"provider": "OpenAI",
"model": "gpt-3.5-turbo",
"prompt": "Ping",
"system_message": "Return {{ return }}",
"formatted_request": {
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "system",
"content": "Return {{ return }}"
},
{
"role": "user",
"content": "Ping"
}
],
"max_tokens": 4096,
"temperature": 0.5,
"top_p": 1,
"presence_penalty": 0,
"frequency_penalty": 0
},
"hash": "SXFsFvCo",
"commit_title": "Updated API parameters",
"commit_description": "Increased temperature",
"prompt_tokens": 1,
"system_message_tokens": 4,
"committed": true,
"variables": {
"prompt": [],
"system_message": [
"return"
]
},
"project": {
"id": 60,
"name": "Generate Sales Report",
"description": "Generate a sales report",
"groups": [
{
"id": 79,
"name": "Sales Prompts",
"description": "Prompts for the sales team to use"
}
]
},
"branch": {
"id": 56,
"name": "master"
},
"configuration": {
"id": 15,
"max_tokens": 4096,
"temperature": 0.5,
"top_p": 1,
"top_k": null,
"presence_penalty": 0,
"frequency_penalty": 0,
"stop_sequences": null
}
},
"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 |
| The ID of a given project, can be found in your browser's URL bar when viewing that project. |
Headers
Header | Value | Notes |
|
| Generate your API Token and replace |
|
| Required to properly format error responses. |
|
| Optional. |
Body
Field | Value | Notes |
| { | Pass information about the authenticated user in your context to PromptHub logs. |
| { | 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."
}