HomepageAdmin PortalSign up
Resources
Start typing to search…

Using Prompts via the API

Introduction

orq.ai exposes API to manipulate Prompts. These APIs are used to manage and enrich Prompts programmatically. In this page we'll see the common use cases for creating and fetching prompts through the API.

Prerequisite

To get started, an API key is needed to use within SDKs or HTTP API.

📘

To get an API key ready, see Authentication.

SDKs

Node.js

Get started with our Node.js SDK

Python

Get started with our Python SDK

Creating a Prompt

To create a Prompt, we'll be using the Create a Prompt API.

The expected Payload contains many information to define and parameter the Prompt:

  • Name, Description and Path for global configuration.
  • Model Configuration, containing model details, parameters and provider.
  • Messages defining the messages sent to the prompt.
  • Metadata further enriching the prompts information.

An example call would look as follow:

curl --request POST \
     --url https://api.orq.ai/v2/prompts \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ORQ_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "prompt_config": {
    "model_parameters": {
      "responseFormat": null,
      "temperature": 1,
      "maxTokens": 256,
      "topP": 0.7,
      "frequencyPenalty": 0,
      "presencePenalty": 0
    },
    "model": "openai/gpt-4o",
    "model_type": "vision",
    "provider": "openai",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant"
      }
    ]
  },
  "display_name": "MyPrompt",
  "path": "Default/Prompts",
  "metadata": {
    "language": "English"
  },
  "description": "Prompt Description"
}
'
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.prompts.create({
    displayName: "MyPrompt",
    promptConfig: {
      modelParameters: {
        responseFormat: null,
        temperature: 1,
        maxTokens: 256,
        topP: 0.7,
        frequencePenalty: 0,
        presencePenalty: 0
      },
      model: "gpt-4o",
      modelType: "vision",
      provider: "openai",
      messages: [
        {
          role: "system",
          content: "You are a helpful assistant",
        }
      ],
    },
    path: "Default/Prompts",
    metadata: {
     language: "English" 
    }
  });

  console.log(result);
}

run();
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.prompts.create(request={
      "display_name": "MyPrompt",
      "prompt_config": {
        "model_parameters": {
          "responseFormat": null,
          "temperature": 1,
          "maxTokens": 256,
          "topP": 0.7,
          "frequencyPenalty": 0,
          "presencePenalty": 0
        },
        "model": "openai/gpt-4o",
        "model_type": "vision",
        "provider": "openai",
        "messages": [{
          "role": "system",
          "content": "You are a helpful assistant"
        }]
      },
      "display_name": "MyPrompt",
      "path": "Default/Prompts",
      "metadata": {
        "language": "English"
      },
      "description": "Prompt Description"
    })

    assert res is not None

    # Handle response
    print(res)

The API answers with the following response

{
  "display_name": "MyPrompt",
  "description": "Prompt Description",
  "prompt_config": {
    "model": "openai/gpt-4o",
    "model_type": "vision",
    "model_parameters": {
      "temperature": 1,
      "maxTokens": 256,
      "topP": 0.7,
      "frequencyPenalty": 0,
      "presencePenalty": 0,
      "responseFormat": null
    },
    "provider": "openai",
    "version": "xqvy5y4ssaeqkfsh",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant"
      }
    ]
  },
  "metadata": {
    "language": "English"
  },
  "_id": "PROMPT_ID",
  "type": "prompt",
  "owner": "USER_ID",
  "domain_id": "DOMAIN_ID",
  "created": "2025-06-06T12:19:50.426Z",
  "updated": "2025-06-06T12:19:50.426Z",
  "created_by_id": null,
  "updated_by_id": null
}

The prompt id is used for further updates or fetch using the API.

Fetching a Prompt

To fetch a Prompt we'll be using the Retrieve a Prompt API.

A Prompt ID is needed as path parameter for this call.

The API call looks as follow:

curl --request GET \
     --url https://api.orq.ai/v2/prompts/PROMPT_ID \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ORQ_API_KEY'
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.prompts.retrieve({
    id: "<id>",
  });

  console.log(result);
}

run();
from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.prompts.retrieve(id="<id>")

    assert res is not None

    # Handle response
    print(res)

And returns the following payload.

{
  "_id": "PROMPT_ID",
  "display_name": "MyPrompt",
  "prompt_config": {
    "model": "gpt-4o",
    "model_db_id": "<model_id>",
    "model_type": "vision",
    "model_parameters": {
      "temperature": 1,
      "maxTokens": 256,
      "topP": 0.7,
      "frequencyPenalty": 0,
      "presencePenalty": 0,
      "responseFormat": null
    },
    "provider": "openai",
    "integration_id": null,
    "version": "05wlf2wpw1z83cxz",
    "messages": [
      {
        "role": "system",
        "content": "You are a useful assistant"
      }
    ]
  },
  "metadata": {
    "use_cases": [
      "API interaction",
      "Chatbots",
      "Code understanding"
    ],
    "language": "English"
  },
  "type": "prompt",
  "owner": "USER_ID",
  "domain_id": "DOMAIN_ID",
  "created": "2025-06-06T10:56:08.795Z",
  "updated": "2025-06-06T10:57:07.067Z",
  "created_by_id": null,
  "updated_by_id": "USER_ID"
}

👍

Once a Prompt is created, it can be used in other modules such a Playground , Experiment, or Deployment.

Updated about 20 hours ago