⚙️Prompts

Create a prompt

To create a prompt in ZBrain Prompt Manager, send a POST request to the specified URL with the required prompt details. Ensure that the payload includes the name of the prompt and an array of message objects defining roles and content. Proper authorization headers must be included to successfully authenticate the request.

Request URL: https://api.zbrain.ai/promptmanagerms/api/v1/prompts

Request method: POST

Request body parameters

Field
Type
Required
Description

name

string

Yes

Title of the prompt (e.g., "App Instructions")

messages

array

Yes

List of messages that define system behavior or conversation setup

role

string

Yes

The role of the message (e.g., system, user, assistant)

content

string

Yes

Prompt body with structured guidance, rules, and tone

Request headers

  • Authorization: Bearer <<API Key >>

  • Content-Type: application/json

Note: You can retrieve your API Key from: ZBrain

Sample request body

{
  "name": "App Instructions",
  "variables": {
    "platform": "ZBrain"
  },
  "messages": [
    {
      "role": "system",
      "content": "You are a friendly and polite customer service agent for {{platform}}. Your primary responsibility is to assist users by answering their questions accurately and courteously. Always respond in the same language the question is asked, regardless of the language of the text in the context.\n\nBehavior Guidelines:\n\nGreetings:\n- Respond to greetings with appropriate and matching greetings.\n- Example: If a user says \"Hello,\" respond with \"Hello! How can I assist you today?\"\n\nHuman-like Interaction:\n- Respond in a natural, conversational manner.\n- Avoid robotic or overly formal language.\n- Show empathy and support in your responses.\n- Acknowledge user concerns and assure them that you are there to help.\n\nContextual Relevance:\n- Tailor your responses to the context provided.\n- Ensure each response is relevant to the specific question and scenario.\n\nHandling Uncertainty:\n- If you cannot deduce the answer from the context, say:\n\"I couldn't find a specific answer to your question. To assist you better, please provide additional details or rephrase your question.\"\n\nAttention Required Responses:\n- If any previous conversation contains the line \"This answer requires attention,\" and the same question is asked again, provide a better, non-identical response.\n\nVisual Elements:\n- Do not generate or display visual elements in your responses."
    }
  ]
}

Code snippets

cURL

Python (Requests)

NodeJs - Request

Sample response

Get prompt by ID

To retrieve a specific prompt by its unique identifier, send a GET request to the endpoint with the prompt ID as a path parameter.

Request URL: https://api.zbrain.ai/promptmanagerms/api/v1/prompts/:id

Request method: GET

Path parameters id - The unique Prompt ID (available on the Prompt Overview page)

Request headers

  • Authorization: Bearer <<API Key >>

  • Content-Type: application/json

Sample request https://api.zbrain.ai/promptmanagerms/api/v1/prompts/681eacd7f51048bb8e33e4fb

Code snippets

cURL

NodeJs - Request

Python(Requests)

Sample response

Update a prompt

To update the content of an existing prompt, send a PUT request to the specific prompt's endpoint using its unique ID. You can modify prompt messages and update their status.

Request URL: https://api.zbrain.ai/promptmanagerms/api/v1/prompts/:id

Request method: PUT

Path parameters

id- The unique Prompt ID (found in the Overview page)

Request headers

  • Authorization: Bearer <<API Key >>

  • Content-Type: application/json

Request body parameters

Field
Type

messages

array

Yes

List of messages defining the prompt logic

role

string

Yes

Role for the message

content

string

Yes

Message text that instructs or simulates behavior, depending on the role

status

string

Yes

Either "DRAFT" or "PUBLISHED"

evaluators

array

No

List of evaluator IDs

Sample request body

Code snippets

cURL

NodeJs - Request

Python (Requests)

Sample response

Delete a prompt

To remove a prompt from the system, send a DELETE request to the endpoint using the prompt’s unique ID. This action is irreversible and will permanently remove the prompt from your workspace.

Request URL: https://api.zbrain.ai/promptmanagerms/api/v1/prompts/:id

Request method: DELETE

Path parameters

id- The unique Prompt ID (available on the overview page)

Request headers

  • Authorization: Bearer <<API Key >>

  • Content-Type: application/json

Sample request https://api.zbrain.ai/promptmanagerms/api/v1/prompts/681eacd7f51048bb8e33e4fb

Code snippets

cURL

NodeJs- Request

Python (Requests)

Sample response

Get all prompts

Fetch a list of all prompts created in Prompt Manager. You can optionally filter, sort, or paginate the results using query parameters.

Request URL: https://api.zbrain.ai/promptmanagerms/api/v1/prompts

Request method: GET

Request headers

  • Authorization: Bearer <<API Key >>

  • Content-Type: application/json

Query parameters

Parameter
Type
Description

key

string

Search by prompt ID

searchQuery

string

Filter prompts by name or message content

sortKey

string

Sort by a specific field, e.g., addedOn, modifiedOn

order

string

asc or desc order of sorting

status

string

Filter prompts by status: DRAFT or PUBLISHED

skip

number

Number of records to skip (for pagination)

limit

number

Max number of records to return

Code snippets

cURL

NodeJs - Request

Python(Requests)

Sample response

Get prompt stats

This API provides detailed usage and performance analytics for a specific prompt, including token usage, latency, cost, and usage trends over time. You must supply the prompt ID and, optionally, its version ID.

Request URL: https://api.zbrain.ai/promptmanagerms/api/v1/prompts/:id/stats

Request method: GET

Path parameters

id- The unique Prompt ID (available on the overview page)

Request headers

  • Authorization: Bearer <<API Key >>

  • Content-Type: application/json

Query parameters (Optional)

Parameter
Type
Description

versionId

string

ID of the specific prompt version to get stats for

Code snippets

cURL

NodeJs- Request

Python(Requests)

Sample response

Last updated