Prompts API

Prompts are reusable query templates with variable placeholders. This page documents all prompt-related endpoints.

The Prompt Object

json

1{
2  "id": "prompt_abc123def456",
3  "title": "Contract Risk Assessment",
4  "description": "Analyze a contract for potential risks",
5  "content": "Analyze the following contract for {{company_name}} and identify:\n1. Liability risks\n2. Termination clauses\n3. Payment terms",
6  "variables": ["company_name"],
7  "datastore_id": null,
8  "folder_id": "folder_xyz789",
9  "is_favorite": true,
10  "created_at": "2024-01-15T10:30:00Z",
11  "updated_at": "2024-01-15T10:30:00Z",
12  "created_by": "user_xyz789"
13}

Attributes

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier for the prompt | | title | string | Display title of the prompt | | description | string | Optional description | | content | string | The prompt template with {{variable}} placeholders | | variables | array | Extracted variable names from content | | datastore_id | string | Associated datastore ID, or null for workspace-level | | folder_id | string | Parent folder ID, or null | | is_favorite | boolean | Whether marked as favorite | | created_at | string | ISO 8601 timestamp of creation | | updated_at | string | ISO 8601 timestamp of last update | | created_by | string | User ID who created the prompt |

List Prompts

GET/v1/prompts

Returns a list of all prompts in your workspace

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | limit | integer | Number of prompts to return (1-100, default 20) | | cursor | string | Pagination cursor from previous response | | datastore_id | string | Filter by datastore (use null for workspace-level) | | folder_id | string | Filter by folder | | favorites_only | boolean | Only return favorites |

Response

json

1{
2  "data": [
3    {
4      "id": "prompt_abc123",
5      "title": "Contract Risk Assessment",
6      "description": "Analyze a contract for potential risks",
7      "variables": ["company_name"],
8      "is_favorite": true,
9      "created_at": "2024-01-15T10:30:00Z"
10    }
11  ],
12  "has_more": false,
13  "next_cursor": null
14}

Example

bash

1curl https://api.orka.ai/v1/prompts?favorites_only=true \
2  -H "Authorization: Bearer sk_your_api_key"

Create Prompt

POST/v1/prompts

Creates a new prompt

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | title | string | Yes | Display title (1-100 characters) | | content | string | Yes | The prompt template | | description | string | No | Optional description | | datastore_id | string | No | Associate with a specific datastore | | folder_id | string | No | Place in a folder |

Variable Syntax

Use {{variable_name}} for placeholders. Variables are automatically extracted.

Optionally provide defaults with {{variable_name|default_value}}.

Example Request

bash

1curl -X POST https://api.orka.ai/v1/prompts \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "title": "Document Summary",
6    "description": "Generate a summary of a document",
7    "content": "Summarize the {{document_type|report}} for {{company_name}}.\n\nFocus on:\n- Key findings\n- Action items\n- Risks\n\nOutput format: {{format|bullet points}}"
8  }'

Response

json

1{
2  "id": "prompt_new123",
3  "title": "Document Summary",
4  "description": "Generate a summary of a document",
5  "content": "Summarize the {{document_type|report}} for {{company_name}}...",
6  "variables": ["document_type", "company_name", "format"],
7  "datastore_id": null,
8  "folder_id": null,
9  "is_favorite": false,
10  "created_at": "2024-01-15T12:00:00Z",
11  "updated_at": "2024-01-15T12:00:00Z"
12}

Get Prompt

GET/v1/prompts/:id

Retrieves a specific prompt by ID

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The prompt ID (e.g., prompt_abc123) |

Example

bash

1curl https://api.orka.ai/v1/prompts/prompt_abc123 \
2  -H "Authorization: Bearer sk_your_api_key"

Update Prompt

PUT/v1/prompts/:id

Updates an existing prompt

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The prompt ID to update |

Request Body

| Field | Type | Description | |-------|------|-------------| | title | string | New title | | description | string | New description | | content | string | New content | | folder_id | string | Move to a different folder |

Example

bash

1curl -X PUT https://api.orka.ai/v1/prompts/prompt_abc123 \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "content": "Updated prompt content with {{new_variable}}"
6  }'

Delete Prompt

DELETE/v1/prompts/:id

Permanently deletes a prompt

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The prompt ID to delete |

Example

bash

1curl -X DELETE https://api.orka.ai/v1/prompts/prompt_abc123 \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "id": "prompt_abc123",
3  "deleted": true
4}

Favorite Prompt

POST/v1/prompts/:id/favorite

Mark a prompt as favorite

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The prompt ID |

Example

bash

1curl -X POST https://api.orka.ai/v1/prompts/prompt_abc123/favorite \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "id": "prompt_abc123",
3  "is_favorite": true
4}

Unfavorite Prompt

DELETE/v1/prompts/:id/favorite

Remove prompt from favorites

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The prompt ID |

Example

bash

1curl -X DELETE https://api.orka.ai/v1/prompts/prompt_abc123/favorite \
2  -H "Authorization: Bearer sk_your_api_key"

Folders

Organize prompts into folders.

List Folders

GET/v1/prompts/folders

List all prompt folders

Example

bash

1curl https://api.orka.ai/v1/prompts/folders \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "data": [
3    {
4      "id": "folder_xyz789",
5      "name": "Legal Analysis",
6      "prompt_count": 5,
7      "created_at": "2024-01-15T10:00:00Z"
8    }
9  ]
10}

Create Folder

POST/v1/prompts/folders

Create a new folder

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Folder name |

Example

bash

1curl -X POST https://api.orka.ai/v1/prompts/folders \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Sales Prompts"
6  }'

Response

json

1{
2  "id": "folder_new456",
3  "name": "Sales Prompts",
4  "prompt_count": 0,
5  "created_at": "2024-01-15T12:00:00Z"
6}

Update Folder

PUT/v1/prompts/folders/:id

Rename a folder

Delete Folder

DELETE/v1/prompts/folders/:id

Delete a folder

Deleting a folder moves all prompts in that folder to the root level. Prompts are not deleted.

Use Prompt in Chat

When using a prompt with the chat API, you can reference it by ID and provide variable values:

bash

1curl -X POST https://api.orka.ai/v1/agents/agt_abc123/chat \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "prompt_id": "prompt_abc123",
6    "variables": {
7      "company_name": "Acme Corp",
8      "document_type": "quarterly report"
9    }
10  }'

The prompt content will be expanded with the provided variable values and sent as the message.