Prompts API

Create, version, and manage AI prompts with system/user messages, tools, variables, and model configurations

GET

/tenants/{tenantId}/prompts

Auth Required

List Prompts

Retrieve a paginated list of all prompts for a tenant

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace

Query Parameters

Name	Type	Description
page	`number`	Page number for pagination Default: `1`
per_page	`number`	Number of results per page (max: 100) Default: `20`
multiStep	`boolean`	Filter by multi-step prompts (true) or single-step (false)

Examples

curl -X GET \
  'https://api.staging.agnt.ai/tenants/tenant_123/prompts?page=1&per_page=20' \
  -H 'Authorization: Bearer sk_live_your_service_key_here' \
  -H 'Content-Type: application/json'

Response Example

200 OK

{
  "data": [
    {
      "tenantId": "tenant_123",
      "promptName": "customer_support_agent",
      "category": "Support",
      "description": "Handles customer inquiries and support tickets",
      "enabled": true,
      "multiStep": false,
      "models": [
        {
          "id": "model_1",
          "provider": "anthropic",
          "name": "claude-3-5-sonnet-20241022",
          "metadata": {}
        }
      ],
      "modelSampling": false,
      "etag": "v1_abc123",
      "publishedEtag": "v1_abc123",
      "publishedVersion": "1",
      "hasUnpublishedChanges": false,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "has_more": false
}

GET

/tenants/{tenantId}/prompts/{promptName}

Auth Required

Get Prompt

Retrieve detailed information about a specific prompt

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace
promptName Required	`string`	Unique name identifier for the prompt

Examples

curl -X GET \
  'https://api.staging.agnt.ai/tenants/tenant_123/prompts/customer_support_agent' \
  -H 'Authorization: Bearer sk_live_your_service_key_here' \
  -H 'Content-Type: application/json'

Response Example

200 OK

{
  "data": {
    "tenantId": "tenant_123",
    "promptName": "customer_support_agent",
    "category": "Support",
    "description": "Handles customer inquiries and support tickets",
    "enabled": true,
    "multiStep": false,
    "systemChunks": [
      {
        "id": "chunk_1",
        "content": "You are a helpful customer support agent...",
        "order": 0,
        "comments": [],
        "metadata": {}
      }
    ],
    "userChunks": [],
    "toolDefs": [
      {
        "id": "tool_1",
        "name": "search_knowledge_base",
        "description": "Search the knowledge base for answers",
        "parameters": {
          "type": "object",
          "properties": {
            "query": { "type": "string", "description": "Search query" }
          },
          "required": ["query"]
        },
        "metadata": {}
      }
    ],
    "variables": [
      {
        "id": "var_1",
        "name": "customer_name",
        "type": "string",
        "required": true,
        "description": "Name of the customer",
        "metadata": {}
      }
    ],
    "scenarios": [],
    "blocks": [],
    "models": [
      {
        "id": "model_1",
        "provider": "anthropic",
        "name": "claude-3-5-sonnet-20241022",
        "metadata": {}
      }
    ],
    "modelSampling": false,
    "etag": "v1_abc123",
    "publishedEtag": "v1_abc123",
    "publishedVersion": "1",
    "hasUnpublishedChanges": false,
    "renderedSystemPrompt": "You are a helpful customer support agent...",
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

POST

/tenants/{tenantId}/prompts

Auth Required

Create Prompt

Create a new prompt template

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace

Request Body

Name	Type	Description
promptName Required	`string`	Unique name identifier for the prompt (lowercase, underscores)
category Required	`string`	Category for organizing prompts
description Required	`string`	Description of the prompt purpose
enabled	`boolean`	Whether the prompt is enabled
systemChunks	`array`	Array of system message chunks
userChunks	`array`	Array of user message chunks
toolDefs	`array`	Array of tool definitions
variables	`array`	Array of variable definitions
scenarios	`array`	Array of test scenarios
models	`array`	Array of model configurations
modelSampling	`boolean`	Whether to enable model sampling

Examples

curl -X POST \
  'https://api.staging.agnt.ai/tenants/tenant_123/prompts' \
  -H 'Authorization: Bearer sk_live_your_service_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "promptName": "customer_support_agent",
    "category": "Support",
    "description": "Handles customer inquiries",
    "enabled": true,
    "systemChunks": [
      {
        "content": "You are a helpful customer support agent...",
        "order": 0,
        "metadata": {}
      }
    ],
    "models": [
      {
        "provider": "anthropic",
        "name": "claude-3-5-sonnet-20241022",
        "metadata": {}
      }
    ]
  }'

Response Example

200 OK

{
  "data": {
    "tenantId": "tenant_123",
    "promptName": "customer_support_agent",
    "category": "Support",
    "description": "Handles customer inquiries",
    "enabled": true,
    "etag": "v1_abc123",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

PATCH

/tenants/{tenantId}/prompts/{promptName}

Auth Required

Update Prompt

Update an existing prompt (creates a new draft version)

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace
promptName Required	`string`	Unique name identifier for the prompt

Request Body

Name	Type	Description
category	`string`	Category for organizing prompts
description	`string`	Description of the prompt purpose
enabled	`boolean`	Whether the prompt is enabled
systemChunks	`array`	Array of system message chunks
userChunks	`array`	Array of user message chunks
toolDefs	`array`	Array of tool definitions
variables	`array`	Array of variable definitions
models	`array`	Array of model configurations
skillset	`array`	Array of skills for the agent
allowedActions	`array`	Array of allowed actions
metadata	`object`	Additional metadata

Examples

curl -X PATCH \
  'https://api.staging.agnt.ai/tenants/tenant_123/prompts/customer_support_agent' \
  -H 'Authorization: Bearer sk_live_your_service_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Updated description",
    "systemChunks": [
      {
        "content": "You are an expert customer support agent...",
        "order": 0,
        "metadata": {}
      }
    ]
  }'

Response Example

200 OK

{
  "data": {
    "tenantId": "tenant_123",
    "promptName": "customer_support_agent",
    "etag": "v2_def456",
    "hasUnpublishedChanges": true,
    "updatedAt": "2024-01-16T10:30:00Z"
  }
}

DELETE

/tenants/{tenantId}/prompts/{promptName}

Auth Required

Delete Prompt

Delete a prompt template

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace
promptName Required	`string`	Unique name identifier for the prompt

Examples

curl -X DELETE \
  'https://api.staging.agnt.ai/tenants/tenant_123/prompts/customer_support_agent' \
  -H 'Authorization: Bearer sk_live_your_service_key_here'

Response Example

200 OK

{
  "message": "Prompt deleted successfully"
}

POST

/tenants/{tenantId}/prompts/{promptName}/publish

Auth Required

Publish Prompt

Publish the current draft version of a prompt, creating a new version

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace
promptName Required	`string`	Unique name identifier for the prompt

Examples

curl -X POST \
  'https://api.staging.agnt.ai/tenants/tenant_123/prompts/customer_support_agent/publish' \
  -H 'Authorization: Bearer sk_live_your_service_key_here'

Response Example

200 OK

{
  "data": {
    "tenantId": "tenant_123",
    "promptName": "customer_support_agent",
    "publishedVersion": "2",
    "publishedEtag": "v2_def456",
    "hasUnpublishedChanges": false,
    "updatedAt": "2024-01-16T11:00:00Z"
  }
}

GET

/tenants/{tenantId}/prompts/{promptName}/versions

Auth Required

List Prompt Versions

Retrieve all published versions of a prompt

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace
promptName Required	`string`	Unique name identifier for the prompt

Query Parameters

Name	Type	Description
page	`number`	Page number for pagination Default: `1`
per_page	`number`	Number of results per page Default: `20`

Examples

curl -X GET \
  'https://api.staging.agnt.ai/tenants/tenant_123/prompts/customer_support_agent/versions' \
  -H 'Authorization: Bearer sk_live_your_service_key_here'

Response Example

200 OK

{
  "data": [
    {
      "versionNumber": "2",
      "etag": "v2_def456",
      "createdAt": "2024-01-16T11:00:00Z"
    },
    {
      "versionNumber": "1",
      "etag": "v1_abc123",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "has_more": false
}

GET

/tenants/{tenantId}/prompts/{promptName}/versions/{versionNumber}

Auth Required

Get Prompt Version

Retrieve a specific version of a prompt with full details including block snapshots

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace
promptName Required	`string`	Unique name identifier for the prompt
versionNumber Required	`string`	Version number to retrieve

Examples

curl -X GET \
  'https://api.staging.agnt.ai/tenants/tenant_123/prompts/customer_support_agent/versions/1' \
  -H 'Authorization: Bearer sk_live_your_service_key_here'

Response Example

200 OK

{
  "data": {
    "tenantId": "tenant_123",
    "promptName": "customer_support_agent",
    "versionNumber": "1",
    "category": "Support",
    "description": "Handles customer inquiries and support tickets",
    "enabled": true,
    "systemChunks": [
      {
        "id": "chunk_1",
        "content": "You are a helpful customer support agent...",
        "order": 0,
        "comments": [],
        "metadata": {}
      }
    ],
    "userChunks": [],
    "toolDefs": [],
    "variables": [],
    "blocks": [
      {
        "blockName": "greeting_template",
        "content": "Hello {{customer_name}}!",
        "description": "Standard greeting template"
      }
    ],
    "models": [
      {
        "id": "model_1",
        "provider": "anthropic",
        "name": "claude-3-5-sonnet-20241022",
        "metadata": {}
      }
    ],
    "etag": "v1_abc123",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}