Skip to main content
All CollectionsAPI
PromptHub API Documentation
PromptHub API Documentation

PromptHub API Reference

Dalton Pierce avatar
Written by Dalton Pierce
Updated this week

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

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/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

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

The ID of a given team, can be found in your browser's URL bar when viewing your "Team Settings"

?group=Group%20Name

(Optional) List Projects from a specific Group. Must be URL-encoded if the group name contains spaces or other special characters.

?model=gpt-4o-mini

(Optional) List Projects where the "head" uses a specific model.

?provider=OpenAI

(Optional) List Projects where the "head" uses a specific model provider: (OpenAI, Anthropic, Azure, Google, Amazon)

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/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

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.

?branch=staging

(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

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?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

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.

?hash=577632e2

(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)

?branch=staging

(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

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

variables

{ 
"type": $typeVar,
"subject": $subjectVar,
...
}

Fill variable placeholders with contextual data.

prompt

Generate a LinkedIn post about {{ subject }}

(Chat projects only) A message passed to the Chat model as the last "user" role message. Supports {{ variable }} placeholders. User messages can also be passed to messages field.

messages

[
[
'role' => 'system',
'content' => 'You are a virtual assistant'
],
[
'role' => 'user',
'content' => 'I want you to generate social media posts for me'
],
[
'role' => 'assistant',
'content' => 'No problem! What can I help you with first?'
],
...
]

(Chat projects only) Allows you to simulate chatbot message history. The messages field is appended to the messages defined in your Project's "Template" section. Each message must include a role and content. Valid roles are ['system', 'user', 'assistant', 'tool'].

hash

577632e2

(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.

branch

staging

(Optional) Use the "head" of a specific branch. Defaults to your project's master/main branch.

metadata

{ 
"user_id": $userId,
"user_email": $email,
"user_name": $name,
"user_avatar": $avatar,
...
}

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

Did this answer your question?