Guides

Prompts

Manage reusable system prompts, understand global vs tenant prompts, and link them to assistants.

A prompt is a reusable system-prompt text that an assistant references by ID. Instead of hard-coding behavior into each assistant, you can maintain one prompt and point several assistants at it — via promptId (voice calls), chatPromptId (chat/messaging), or whisperSummaryPromptId (warm-transfer whisper summaries).

Method	Path	Purpose
GET	`/prompts`	List prompts (optionally including global ones)
GET	`/prompts/{id}`	Get one prompt
POST	`/prompts`	Create a prompt
PUT	`/prompts/{id}`	Replace a prompt
DELETE	`/prompts/{id}`	Delete a prompt

Prompt types#

Every prompt has a type that determines which assistant slot it can fill:

Type	Assistant field	Used for
`voice` (default)	`promptId`	Voice calls
`chat`	`chatPromptId`	Chat / messaging conversations
`whisper_summary`	`whisperSummaryPromptId`	The summary whispered to a human agent during a warm transfer

If you omit type on create, it defaults to voice.

Global vs tenant prompts#

Prompts come in two flavors:

Tenant prompts — created by you, scoped to your tenant. You can create, update, and delete them.
Global prompts — platform-provided prompts available to every tenant. They are read-only: you can list them (with includeGlobal=true), fetch them by ID, and reference them from assistants, but update and delete only apply to prompts your tenant owns.

Global prompts have a tenantId of null in responses, so you can tell them apart in a mixed listing.

List prompts#

GET /prompts

Query param	Type	Required	Description
`limit`	number	No	Page size
`offset`	number	No	Items to skip
`includeGlobal`	`"true"` \| `"false"`	No	Include global (platform) prompts. Default `false`.
`search`	string	No	Filter by prompt name
`type`	`voice` \| `chat` \| `whisper_summary`	No	Filter by prompt type

bash

curl "https://core-api.heysadie.ai/prompts?includeGlobal=true&type=voice" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Create a prompt#

POST /prompts

Field	Type	Required	Description
`prompt`	string	Yes	The prompt text
`name`	string	No	Display name, max 150 characters
`type`	`voice` \| `chat` \| `whisper_summary`	No	Defaults to `voice`

bash

curl -X POST https://core-api.heysadie.ai/prompts \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Restaurant receptionist",
    "type": "voice",
    "prompt": "You are a friendly receptionist for a restaurant. Keep answers short and confirm bookings back to the caller."
  }'

Update a prompt#

PUT /prompts/{id} — a full replace with the same body as create (prompt required, name and type optional). Omitting type leaves the stored type unchanged. Only prompts owned by your tenant can be updated.

Terminal

curl -X PUT https://core-api.heysadie.ai/prompts/PROMPT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Restaurant receptionist v2", "prompt": "..." }'

Delete a prompt#

DELETE /prompts/{id} — soft-deletes the prompt. Only tenant-owned prompts can be deleted.

Terminal

curl -X DELETE https://core-api.heysadie.ai/prompts/PROMPT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY"

Link a prompt to an assistant#

Set the matching field on the assistant (create or PATCH /assistants/{id}):

Terminal

curl -X PATCH https://core-api.heysadie.ai/assistants/ASSISTANT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "promptId": "PROMPT_ID" }'

If promptId is not set, the assistant uses the default prompt. chatPromptId and whisperSummaryPromptId are nullable, so you can unset them by sending null.

Next steps#

Assistants — where prompts get used.
Custom instructions — small per-assistant behavior tweaks that don't warrant a whole prompt.

PreviousAssistants NextTools