# Create a prompt template

div
strong
🔨 In Development
 — This section is still being developed and may change.


Creates a reusable prompt template that can be referenced in model response requests. Prompt templates allow you to define standardized instructions, system prompts, or complex workflows once and reuse them across multiple API calls with dynamic variable substitution.

Prompt templates support variable substitution where placeholders in the template are replaced with actual values at runtime. This enables flexible, parameterized prompts for consistent AI behavior across different use cases.

#### Request Body

**`organizationId`** string *required*

The unique identifier of the organization to which this prompt belongs. All API requests must be scoped to an organization for billing, access control, and resource management. Find your organization ID in [Freddy Hub → Settings → Organization](https://freddy-hub.aitronos.com/settings/organization).

**`name`** string *required*

A human-readable name for the prompt template. Used for identification in the Freddy Hub dashboard and API listings.

**`description`** string *optional*

A detailed description of what the prompt template does and when it should be used. Helps developers understand the template's purpose and usage.

**`content`** string *required*

The prompt template content with variable placeholders. Use `{{variable_name}}` syntax for variables that will be substituted at runtime.

Example: `"You are a {{role}} assistant. Respond to the user query: {{user_query}}. Target audience: {{audience}}"`

**`variables`** object *optional*

Defines the expected variables for this prompt template, including their types, descriptions, and whether they're required. This schema is used for validation and IDE autocompletion when using the template.

details
summary
Show structure
Each variable definition:

**`name`** string *required*

The variable name as referenced in the template (e.g., `{{user_query}}`).

**`type`** string *required*

The data type of the variable. Available types: `string`, `number`, `boolean`, `array`, `object`, `image`, `file`.

**`description`** string *optional*

Description of what the variable represents and how it should be used.

**`required`** boolean *optional* · Defaults to `false`

Whether this variable must be provided when using the template.

**`default`** any *optional*

Default value to use if the variable is not provided in the request.

**`enum`** array *optional*

For `string` types, restricts the variable to a specific set of values.

Example:


```json
{
  "variables": {
    "role": {
      "type": "string",
      "description": "The role the AI should assume",
      "required": true,
      "enum": ["helpful_assistant", "code_reviewer", "creative_writer"]
    },
    "user_query": {
      "type": "string",
      "description": "The user's input or question",
      "required": true
    },
    "max_length": {
      "type": "number",
      "description": "Maximum response length in words",
      "default": 200,
      "required": false
    }
  }
}
```

**`tags`** array *optional*

Array of tags to categorize and filter prompt templates. Useful for organizing templates by use case, team, or project.

**`isPublic`** boolean *optional* · Defaults to `false`

Whether this prompt template can be accessed by other organizations or team members. Public templates are discoverable in the Freddy Hub template gallery.

**`metadata`** object *optional*

Custom key-value pairs for attaching additional information to the prompt template. Useful for internal tracking, versioning notes, or integration metadata.

## Returns

A [PromptResponse](#promptresponse) object containing the API response data.

Basic template

```bash
curl https://api.freddy.aitronos.com/v1/prompts \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "organizationId": "org_abc123",
  "name": "Code Review Assistant",
  "description": "Reviews code pull requests and provides improvement suggestions",
  "content": "You are an expert code reviewer. Analyze the following code and provide constructive feedback focusing on {{focus_areas}}. Code to review:\n\n{{code}}\n\nLanguage: {{language}}",
  "variables": {
    "focus_areas": {
      "type": "string",
      "description": "Areas to focus the review on (e.g., security, performance, readability)",
      "required": false,
      "default": "best practices"
    },
    "code": {
      "type": "string",
      "description": "The code to review",
      "required": true
    },
    "language": {
      "type": "string",
      "description": "Programming language of the code",
      "required": true,
      "enum": ["javascript", "python", "java", "go", "rust", "typescript"]
    }
  },
  "tags": ["code-review", "development", "quality"]
}'
```


```python
import requests
import os

response = requests.post(
  "https://api.freddy.aitronos.com/v1/prompts",
  headers={
      "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}",
      "Content-Type": "application/json"
  },
  json={
      "organizationId": "org_abc123",
      "name": "Code Review Assistant",
      "description": "Reviews code pull requests and provides improvement suggestions",
      "content": "You are an expert code reviewer. Analyze the following code and provide constructive feedback focusing on {{focus_areas}}. Code to review:\n\n{{code}}\n\nLanguage: {{language}}",
      "variables": {
          "focus_areas": {
              "type": "string",
              "description": "Areas to focus the review on (e.g., security, performance, readability)",
              "required": False,
              "default": "best practices"
          },
          "code": {
              "type": "string",
              "description": "The code to review",
              "required": True
          },
          "language": {
              "type": "string",
              "description": "Programming language of the code",
              "required": True,
              "enum": ["javascript", "python", "java", "go", "rust", "typescript"]
          }
      },
      "tags": ["code-review", "development", "quality"]
  }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/prompts', {
method: 'POST',
headers: {
  'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`,
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  organizationId: 'org_abc123',
  name: 'Code Review Assistant',
  description: 'Reviews code pull requests and provides improvement suggestions',
  content: 'You are an expert code reviewer. Analyze the following code and provide constructive feedback focusing on {{focus_areas}}. Code to review:\n\n{{code}}\n\nLanguage: {{language}}',
  variables: {
    focus_areas: {
      type: 'string',
      description: 'Areas to focus the review on (e.g., security, performance, readability)',
      required: false,
      default: 'best practices'
    },
    code: {
      type: 'string',
      description: 'The code to review',
      required: true
    },
    language: {
      type: 'string',
      description: 'Programming language of the code',
      required: true,
      enum: ['javascript', 'python', 'java', 'go', 'rust', 'typescript']
    }
  },
  tags: ['code-review', 'development', 'quality']
})
});

const result = await response.json();
console.log(result);
```

Template with default values

```bash
curl https://api.freddy.aitronos.com/v1/prompts \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "organizationId": "org_abc123",
  "name": "Customer Support Bot",
  "description": "Standard customer support responses with escalation options",
  "content": "You are {{persona_name}}, a {{experience_level}} customer support specialist. Greet the customer and address their issue: {{customer_issue}}. If the issue requires escalation, use the escalation protocol. Current time: {{current_time}}",
  "variables": {
    "persona_name": {
      "type": "string",
      "description": "Name of the AI persona",
      "required": false,
      "default": "Alex"
    },
    "experience_level": {
      "type": "string",
      "description": "Experience level of the support agent",
      "required": false,
      "default": "senior",
      "enum": ["junior", "intermediate", "senior"]
    },
    "customer_issue": {
      "type": "string",
      "description": "Description of the customer's issue",
      "required": true
    },
    "current_time": {
      "type": "string",
      "description": "Current timestamp for time-sensitive responses",
      "required": false,
      "default": "{{now}}"
    }
  },
  "isPublic": false,
  "metadata": {
    "department": "support",
    "version": "1.0",
    "createdBy": "support-team"
  }
}'
```


```python
import requests
import os
from datetime import datetime

response = requests.post(
  "https://api.freddy.aitronos.com/v1/prompts",
  headers={
      "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}",
      "Content-Type": "application/json"
  },
  json={
      "organizationId": "org_abc123",
      "name": "Customer Support Bot",
      "description": "Standard customer support responses with escalation options",
      "content": "You are {{persona_name}}, a {{experience_level}} customer support specialist. Greet the customer and address their issue: {{customer_issue}}. If the issue requires escalation, use the escalation protocol. Current time: {{current_time}}",
      "variables": {
          "persona_name": {
              "type": "string",
              "description": "Name of the AI persona",
              "required": False,
              "default": "Alex"
          },
          "experience_level": {
              "type": "string",
              "description": "Experience level of the support agent",
              "required": False,
              "default": "senior",
              "enum": ["junior", "intermediate", "senior"]
          },
          "customer_issue": {
              "type": "string",
              "description": "Description of the customer's issue",
              "required": True
          },
          "current_time": {
              "type": "string",
              "description": "Current timestamp for time-sensitive responses",
              "required": False,
              "default": "{{now}}"
          }
      },
      "isPublic": False,
      "metadata": {
          "department": "support",
          "version": "1.0",
          "createdBy": "support-team"
      }
  }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/prompts', {
method: 'POST',
headers: {
  'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`,
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  organizationId: 'org_abc123',
  name: 'Customer Support Bot',
  description: 'Standard customer support responses with escalation options',
  content: 'You are {{persona_name}}, a {{experience_level}} customer support specialist. Greet the customer and address their issue: {{customer_issue}}. If the issue requires escalation, use the escalation protocol. Current time: {{current_time}}',
  variables: {
    persona_name: {
      type: 'string',
      description: 'Name of the AI persona',
      required: false,
      default: 'Alex'
    },
    experience_level: {
      type: 'string',
      description: 'Experience level of the support agent',
      required: false,
      default: 'senior',
      enum: ['junior', 'intermediate', 'senior']
    },
    customer_issue: {
      type: 'string',
      description: 'Description of the customer's issue',
      required: true
    },
    current_time: {
      type: 'string',
      description: 'Current timestamp for time-sensitive responses',
      required: false,
      default: '{{now}}'
    }
  },
  isPublic: false,
  metadata: {
    department: 'support',
    version: '1.0',
    created_by: 'support-team'
  }
})
});

const result = await response.json();
console.log(result);
```

Template with file variables

```bash
curl https://api.freddy.aitronos.com/v1/prompts \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "organizationId": "org_abc123",
  "name": "Document Analysis Template",
  "description": "Analyzes uploaded documents and extracts key information",
  "content": "You are a document analysis expert. Analyze the document {{document_file}} and extract the following information:\n\n{{extraction_criteria}}\n\nProvide your analysis in {{output_format}} format.",
  "variables": {
    "document_file": {
      "type": "file",
      "description": "The document file to analyze (PDF, DOCX, TXT)",
      "required": true
    },
    "extraction_criteria": {
      "type": "string",
      "description": "What specific information to extract from the document",
      "required": true
    },
    "outputFormat": {
      "type": "string",
      "description": "Desired output format",
      "required": false,
      "default": "json",
      "enum": ["json", "markdown", "html", "plain_text"]
    },
    "reference_image": {
      "type": "image",
      "description": "Optional reference image for visual comparison",
      "required": false
    }
  },
  "tags": ["document-analysis", "extraction", "automation"]
}'
```


```python
response = requests.post(
  "https://api.freddy.aitronos.com/v1/prompts",
  headers={
      "Authorization": f"Bearer {api_key}",
      "Content-Type": "application/json"
  },
  json={
      "organizationId": "org_abc123",
      "name": "Document Analysis Template",
      "description": "Analyzes uploaded documents and extracts key information",
      "content": "You are a document analysis expert. Analyze the document {{document_file}} and extract the following information:\n\n{{extraction_criteria}}\n\nProvide your analysis in {{output_format}} format.",
      "variables": {
          "document_file": {
              "type": "file",
              "description": "The document file to analyze (PDF, DOCX, TXT)",
              "required": True
          },
          "extraction_criteria": {
              "type": "string",
              "description": "What specific information to extract from the document",
              "required": True
          },
          "outputFormat": {
              "type": "string",
              "description": "Desired output format",
              "required": False,
              "default": "json",
              "enum": ["json", "markdown", "html", "plain_text"]
          },
          "reference_image": {
              "type": "image",
              "description": "Optional reference image for visual comparison",
              "required": False
          }
      },
      "tags": ["document-analysis", "extraction", "automation"]
  }
)
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/prompts', {
method: 'POST',
headers: {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  organizationId: 'org_abc123',
  name: 'Document Analysis Template',
  description: 'Analyzes uploaded documents and extracts key information',
  content: 'You are a document analysis expert. Analyze the document {{document_file}} and extract the following information:\n\n{{extraction_criteria}}\n\nProvide your analysis in {{output_format}} format.',
  variables: {
    document_file: {
      type: 'file',
      description: 'The document file to analyze (PDF, DOCX, TXT)',
      required: true
    },
    extraction_criteria: {
      type: 'string',
      description: 'What specific information to extract from the document',
      required: true
    },
    output_format: {
      type: 'string',
      description: 'Desired output format',
      required: false,
      default: 'json',
      enum: ['json', 'markdown', 'html', 'plain_text']
    },
    reference_image: {
      type: 'image',
      description: 'Optional reference image for visual comparison',
      required: false
    }
  },
  tags: ['document-analysis', 'extraction', 'automation']
})
});
```

#### Response

**`id`** string

The unique identifier of the created prompt template.

**`object`** string

Always set to `"prompt"`.

**`name`** string

The name of the prompt template.

**`description`** string

The description of the prompt template.

**`content`** string

The prompt template content.

**`variables`** object

The variable definitions for the template.

**`tags`** array

The tags assigned to the template.

**`isPublic`** boolean

Whether the template is public.

**`metadata`** object

Custom metadata attached to the template.

**`createdAt`** integer

Timestamp when the template was created (Unix timestamp).

**`updatedAt`** integer

Timestamp when the template was last updated (Unix timestamp).

**`version`** string

The version identifier of this template (auto-generated).

## Related Resources

- [Using Prompt Templates in Model Responses](/docs/api-reference/responses/create#prompt)
- [List Prompts](/docs/api-reference/prompts/list)
- [Retrieve Prompt](/docs/api-reference/prompts/retrieve)
- [Update Prompt](/docs/api-reference/prompts/update)