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

Get Authenticated User
Get Your Team's Prompts
Get Your Project's "Head" Prompt
Run Your Project's "Head" Prompt

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
`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,
      "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
`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"

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' \
 --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

{
  "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
`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": {
    "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

{
  "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

{
  "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."
}