Inferences

Prompts API

The Prompts API allows you to manage AI prompts that can be used with inference endpoints. Prompts are reusable templates that can be applied to various AI models for consistent and structured responses.

# List Prompts

Retrieves a list of prompts with optional filtering and pagination.

# Query Parameters

category string (optional)
Filter prompts by category.

is_active boolean (optional)
Filter by active status.

is_user_specific boolean (optional)
Filter by user-specific prompts.

user_id string (optional)
Filter prompts by specific user.

search string (optional)
Search prompts by name, content, or category.

search_strategy string (optional)
Search strategy: match_all or match_some (default: match_some).

order_by string (optional)
Sort by field: created_at, updated_at, name, category (default: created_at).

direction string (optional)
Sort direction: asc or desc (default: desc).

page number (optional)
Page number for pagination (default: 1).

limit number (optional)
Number of items per page (default: 20, max: 100).

# Example Request

        const res = await fetch("https://api.packagex.io/v1/prompts?category=shipping&is_active=true&page=1&limit=10", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
  },
}).then((res) => res.json());

const prompts = res.data;

      

# Response

        {
  "data": [
    {
      "id": "prmpt_1234567890",
      "name": "Shipping Label Parser",
      "prompt": "Extract shipping information from the label...",
      "category": "shipping",
      "is_active": true,
      "is_user_specific": false,
      "user_id": "user_1234567890",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "created_by": "user_1234567890",
      "updated_by": "user_1234567890"
    }
  ],
  "message": "1 prompts retrieved",
  "pagination": {
    "page": 1,
    "limit": 10,
    "total_count": 1,
    "has_more": false
  }
}

      

# Get Prompts Dropdown

Retrieves a simplified list of active prompts for dropdown/selection purposes.

# Example Request

        const res = await fetch("https://api.packagex.io/v1/prompts/dropdown", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
  },
}).then((res) => res.json());

const prompts = res.data;

      

# Response

        {
  "data": [
    {
      "id": "prmpt_1234567890",
      "name": "Shipping Label Parser",
      "prompt": "Extract shipping information from the label..."
    }
  ],
  "message": "1 prompts retrieved for dropdown"
}

      

# Create Prompt

Creates a new prompt. Maximum of 100 prompts allowed per organization.

# Request Body

name string (required)
Name of the prompt (5-100 characters).

prompt string (required)
The prompt content (5-8000 characters).

category string (optional)
Category for organizing prompts (max 50 characters).

is_user_specific boolean (optional)
Whether the prompt is user-specific (default: false).

# Example Request

        const data = {
  name: "Package Classification",
  prompt: "Analyze the package and classify it into one of these categories: electronics, clothing, books, food, or other. Provide reasoning for your classification.",
  category: "classification",
  is_user_specific: false
};

const res = await fetch("https://api.packagex.io/v1/prompts", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const prompt = res.data;

      

# Response

        {
  "data": {
    "id": "prmpt_1234567890",
    "name": "Package Classification",
    "prompt": "Analyze the package and classify it into one of these categories...",
    "category": "classification",
    "is_active": true,
    "is_user_specific": false,
    "user_id": "user_1234567890",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "created_by": "user_1234567890",
    "updated_by": "user_1234567890"
  },
  "message": "Prompt created successfully"
}

      

# Retrieve Prompt

Retrieves a specific prompt by ID.

# Path Parameters

prompt_id string (required)
The unique identifier of the prompt.

# Example Request

        const prompt_id = "prmpt_1234567890";

const res = await fetch(`https://api.packagex.io/v1/prompts/${prompt_id}`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
  },
}).then((res) => res.json());

const prompt = res.data;

      

# Response

        {
  "data": {
    "id": "prmpt_1234567890",
    "name": "Package Classification",
    "prompt": "Analyze the package and classify it into one of these categories...",
    "category": "classification",
    "is_active": true,
    "is_user_specific": false,
    "user_id": "user_1234567890",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "created_by": "user_1234567890",
    "updated_by": "user_1234567890"
  },
  "message": "Prompt retrieved"
}

      

# Update Prompt

Updates an existing prompt. Only the prompt owner or organization admin can update prompts.

# Path Parameters

prompt_id string (required)
The unique identifier of the prompt.

# Request Body

name string (optional)
Updated name of the prompt (5-100 characters).

prompt string (optional)
Updated prompt content (5-8000 characters).

category string (optional)
Updated category for organizing prompts (max 50 characters).

is_active boolean (optional)
Whether the prompt is active.

is_user_specific boolean (optional)
Whether the prompt is user-specific.

# Example Request

        const prompt_id = "prmpt_1234567890";
const data = {
  name: "Enhanced Package Classification",
  prompt: "Analyze the package image and classify it into one of these categories: electronics, clothing, books, food, or other. Provide detailed reasoning for your classification and confidence score.",
  category: "classification",
  is_active: true
};

const res = await fetch(`https://api.packagex.io/v1/prompts/${prompt_id}`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const prompt = res.data;

      

# Response

        {
  "data": {
    "id": "prmpt_1234567890",
    "name": "Enhanced Package Classification",
    "prompt": "Analyze the package image and classify it into one of these categories...",
    "category": "classification",
    "is_active": true,
    "is_user_specific": false,
    "user_id": "user_1234567890",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:45:00Z",
    "created_by": "user_1234567890",
    "updated_by": "user_1234567890"
  },
  "message": "Prompt updated successfully"
}

      

# Delete Prompt

Deletes a specific prompt. Only the prompt owner or organization admin can delete prompts.

# Path Parameters

prompt_id string (required)
The unique identifier of the prompt.

# Example Request

        const prompt_id = "prmpt_1234567890";

const res = await fetch(`https://api.packagex.io/v1/prompts/${prompt_id}`, {
  method: "DELETE",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
  },
}).then((res) => res.json());

const result = res.data;

      

# Response

        {
  "data": {
    "success": true
  },
  "message": "Prompt deleted"
}

      

# Using Prompts with Inferences

Prompts can be used with VLM (Vision Language Model) inferences by referencing the prompt_id in your inference requests:

        const inference_data = {
  image: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASA...",
  prompt_id: "prmpt_1234567890", // Reference to your saved prompt
  model: "orion_small"
};

const res = await fetch("https://api.packagex.io/v0/ai/inferences/images/vlm", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(inference_data),
}).then((res) => res.json());