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
Postman public collection
Integration guides
For more information and examples on how to integrate our API into your code check out our integration guides:
Prerequisites
To interact with the PromptHub API, we need a way to uniquely identify you so we know what teams and projects you have access to. We do this by reading the "Bearer token" attached to your requests.
Visit your API Settings page to generate an API token for your account.
Use API Tokens generated by a team member with appropriate role (owner, admin, editor) to access the projects you want to interact with.
Get 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,
"name": "John Smith",
"email": "john@prompthub.us",
"current_team": {
"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 role-based permissions. Make sure the token is included as a bearer token in the Authorization
header of your request, and that the token itself is preceded by "Bearer ".
{
"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."
}
List Your Projects
A "Project" is how we package up your prompt or chatbot with all its related version history, variables, and logs.
Returns a list of the given team's projects. Includes information about each project's "head" revision (typically this is the last commit on your master/main branch).
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 make a request to our /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" |
| (Optional) List Projects from a specific Group. Must be URL-encoded if the group name contains spaces or other special characters. |
| (Optional) List Projects where the "head" uses a specific model. |
| (Optional) List Projects where the "head" uses a specific model provider: |
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?model=gpt-4o-mini&provider=OpenAI' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
PHP
$url = 'https://app.prompthub.us/api/v1/teams/{id}/projects?group=Test%20Group&provider=Anthropic';
$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?model=claude-3-opus-20240229'
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": 1,
"name": "fugit ducimus",
"description": "Sed quam aut et velit temporibus. Qui nemo libero labore facere. Expedita reprehenderit perferendis voluptates dolores quia quas.",
"head": {
"provider": "Anthropic",
"model": "claude-3-opus-20240229",
"prompt": "Ping",
"system_message": "Return {{ test }}",
"formatted_request": {
"model": "claude-3-opus-20240229",
"prompt": "Return Pong\n\n\nHuman: Ping\n\nAssistant:",
"max_tokens_to_sample": 200000,
"temperature": 0.5,
"top_p": 1,
},
"hash": "c97081db",
"commit_title": "Test",
"commit_description": "test",
"variables": {
"system_message": [],
"prompt": [
"test"
]
},
"branch": {
"name": "master"
},
"configuration": {
"id": 5,
"max_tokens": 200000,
"temperature": 0.5,
"top_p": 1,
}
},
"groups": [
{
"name": "Test Group",
"description": "Collection of test projects"
}
]
},
{
"id": 2,
"name": "ipsam ipsum",
"description": "Saepe tempore et aut est ut inventore 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 role-based permissions. Make sure the token is included as a bearer token in the Authorization
header of your request, and that the token itself is preceded by "Bearer ".
{
"status": "error",
"code": 401,
"message": "Unauthorized. Check your API Token."
}
403 - Forbidden
Your API Token or team role is missing the proper permission to use this API endpoint. Navigate to the API Tokens page, click "Permissions" next to your token and check project:read
. Check your team role by navigating to Team Settings (only team owners and admins can edit member roles).
{
"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."
}
Get a Project's "Head"
Your Project "head" refers to the production-ready version of your prompt - typically the last commit on your master/main branch. Project heads are the primary way the PromptHub API and other features like Chains interact with your Projects.
Get the "Head" revision for a given project. Useful when you want to integrate a prompt stored in PromptHub into your application, but make the LLM API call yourself.
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. |
| (Optional) Use the "head" of a specific branch. Defaults to your project's master/main branch. Can also be passed in request body. Must be URL-encoded if the branch name contains spaces or special characters. |
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?branch=staging';
$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?branch=Test%20Branch'
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,
"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,
},
"hash": "SXFsFvCo",
"commit_title": "Updated API parameters",
"commit_description": "Increased temperature",
"variables": {
"prompt": [],
"system_message": [
"return"
]
},
"project": {
"id": 60,
"name": "Generate Sales Report",
"description": "Generate a sales report",
"groups": [
{
"name": "Sales Prompts",
"description": "Prompts for the sales team to use"
}
]
},
"branch": {
"name": "staging"
},
"configuration": {
"id": 15,
"max_tokens": 4096,
"temperature": 0.5,
"top_p": 1,
}
},
"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 role-based permissions. Make sure the token is included as a bearer token in the Authorization
header of your request, and that the token itself is preceded by "Bearer ".
{
"status": "error",
"code": 401,
"message": "Unauthorized. Check your API Token."
}
403 - Forbidden
Your API Token or team role is missing the proper permission to use this API endpoint. Navigate to the API Tokens page, click "Permissions" next to your token and check project:read
and/or project:run
. Check your team role by navigating to Team Settings (only team owners and admins can edit member roles).
{
"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 working API Keys for your selected model 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 shaped such that it can be passed to your LLM provider's API. But first, you must 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
$rawPrompt = "Generate a {{ type }} about {{ subject }}"
$variables = [
'type' => 'song',
'subject' => 'generative AI',
// ...
]
$variableRegex = "/\{\{\s*([a-zA-Z0-9_-]+)\s*}}/";
$formattedPrompt = preg_replace_callback(
$variableRegex,
static fn ($matches) => $variables[$matches[1]] ?? $matches[0],
$rawPrompt
);
const rawPrompt = "Generate a {{ type }} about {{ subject }}"
const variables = {
type: 'haiku',
subject: 'prompt management',
// ...
};
const variableRegex = /\{\{\s*([a-zA-Z0-9_-]+)\s*}}/g;
const formattedPrompt = rawPrompt.replace(
variableRegex,
(match, variableLabel) => variables[variableLabel] || match
);
Run a Project
Make an LLM request using the "head" revision of the given Project. This endpoint requires your Project to have at least one commit.
This endpoint proxies the LLM API call through PromptHub, and you receive the output.
Your Project's "head" revision is typically the last commit on your master/main branch, unless overridden with the branch=branchName
parameter.
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. |
| (Optional) Use the "hash" of a specific revision. This allows you to run a revision other than the "head" (the most recently committed revision on a branch) |
| (Optional) Use the "head" of a specific branch. Defaults to your project's master/main branch. Can also be passed in request body. Must be URL-encoded if the branch name contains spaces or special characters. |
Headers
Header | Value | Notes |
|
| Generate your API Token and replace |
|
| Required to properly format error responses. |
|
| Optional. |
Body
Field | Value | Notes |
| { | Fill variable placeholders with contextual data. |
| Generate a LinkedIn post about {{ subject }} | (Chat projects only) A message passed to the Chat model as the last "user" role message. Supports |
| [ | (Chat projects only) Allows you to simulate chatbot message history. The |
hash |
| (Optional) Use a specific revision by passing the unique hash. You can find the hash in the project's History tab or in the version history component on the Playground page. |
| staging | (Optional) Use the "head" of a specific branch. Defaults to your project's master/main branch. |
| { | Any metadata or contextual info you want to be associated with this run. Can be seen on your Project's "API" tab. |
Completion Examples
cURL
curl --location https://app.prompthub.us/api/v1/projects/42/run?branch=staging \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
"variables": {
"type": "calculate",
"subject": "life, the universe, and everything"
},
"metadata": {
"user_identifier": 84,
"context": "Calculating the answer to life, the universe, and everything"
}
}'
PHP
$url = 'https://app.prompthub.us/api/v1/projects/42/run';
$headers = [
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer {token}'
];
$data = json_encode([
'branch' => 'Test Branch',
'hash' => '577632e2'
'variables' => [
'type' => 'calculate',
'subject' => 'life, the universe, and everything'
],
'metadata' => [
'user_email' => 'plaid@fourty-two.rocks',
'user_name' => 'Douglas Adams',
'context' => 'Calculating the answer to life, the universe, and everything'
]
]);
$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/42/run?branch=Test%20Branch'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {token}'
}
data = {
'variables': {
'type': 'calculate',
'subject': 'life, the universe, and everything'
},
'metadata': {
'context': 'Calculating the answer to life, the universe, and everything'
}
}
res = requests.post(url, headers=headers, json=data)
print(res.json())
Chat Examples
Chat Projects don't have a predefined "prompt", they have a message history that define how the LLM behaves.
Therefore running a Chat Project requires a prompt
and/or messages
parameter that contain your user query and any additional message history (appended to your project's committed Template messages).
cURL
curl --location https://app.prompthub.us/api/v1/projects/42/run?branch=QA \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
"messages": {
{ "role": "system", "content": "You are Deep Thought, the most powerful supercomputer ever built. Your job is to answer my questions." },
{ "role": "user", "content": "What\'s your name and role?" },
{ "role": "assistant", "content": "I am Deep Thought, a highly advanced supercomputer designed to answer questions and provide information. How may I assist you?" }
},
"prompt": "What\'s the answer to {{ question }}",
"variables": {
"question": "life, the universe, and everything"
},
"metadata": {
"user_email": "plaid@fourty-two.rocks",
"user_name": "Douglas Adams",
"context": "Calculating the answer to life, the universe, and everything"
},
}'
PHP
$url = 'https://app.prompthub.us/api/v1/projects/42/run';
$headers = [
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer {token}'
];
$data = json_encode([
'branch' => 'Test Branch'
'messages' => [
[
'role' => 'system',
'content' => 'You are Deep Thought, the most powerful supercomputer ever built. Your job is to answer my questions.'
],
[
'role' => 'user',
'content' => 'What\'s your name and role?'
],
[
'role' => 'assistant',
'content' => 'I am Deep Thought, a highly advanced supercomputer designed to answer questions and provide information. How may I assist you?'
]
],
'prompt': 'What\'s the answer to {{ question }}',
'variables' => [
'question' => 'life, the universe, and everything'
],
'metadata' => [
'context' => 'Calculating the answer to life, the universe, and everything',
],
]);
$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/42/run?branch=Test%20Branch'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {token}'
}
data = {
'messages': {
{
'role': 'system',
'content': 'You are Deep Thought, the most powerful supercomputer ever built. Your job is to answer my questions.'
},
{
'role': 'user',
'content': 'What\'s your name and role?'
},
{
'role': 'assistant',
'content': "I am Deep Thought, a highly advanced supercomputer designed to answer questions and provide information. How may I assist you?'
}
},
'prompt': 'What\'s the answer to {{ question }}',
'variables': {
'question': 'life, the universe, and everything'
},
'metadata': {
'user_email': 'plaid@fourty-two.rocks',
'user_name': 'Douglas Adams',
}
}
res = requests.post(url, headers=headers, json=data)
print(res.json())
Responses
200 - OK
{
"data": {
"provider": "OpenAI",
"model": "gpt-4o-mini",
"prompt_tokens": 18,
"completion_tokens": 484,
"total_tokens": 502,
"finish_reason": "stop",
"text": "The answer to life, the universe, and everything is... 42.",
"cost": 0.000995,
"latency": 4200, //ms
"network_time": 86, //ms
"total_time": 4286 //ms
},
"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 role-based permissions. Make sure the token is included as a bearer token in the Authorization
header of your request, and that the token itself is preceded by "Bearer ".
{
"status": "error",
"code": 401,
"message": "Unauthorized. Check your API Token."
}
403 - Forbidden
Your API Token or team role is missing the proper permission to use this API endpoint. Navigate to the API Tokens page, click "Permissions" next to your token and check project:read
and/or project:run
. Check your team role by navigating to Team Settings (only team owners and admins can edit member roles).
{
"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."
}
Additional Resources
Anthropic
OpenAI
Azure
Google (Gemini)
Amazon (Bedrock)
Postman public collection
Integration guides