Prompts API Documentation

A prompt is what turns a natural language search into a query: the instructions the library’s language model is given, the metadata types whose tags it is told about, and a set of worked examples. Each library has its own prompts, and every version of a prompt is kept.

Reading is open to every collaborator. Creating, changing, copying and deleting prompts and their versions take the editor role and the catalog_write scope.

Endpoints

GET /api/v1/libraries/{library_id}/ai_prompts

Retrieve the prompts in a library, ordered by name.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Query Parameters

Name	Type	Description
page	integer	Page number for pagination (default: 1)
per_page	integer	Records per page, up to 200 (default: 25)

Response

{
    "pagination": {
        "total_entries": 2,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 1
    },
    "ai_prompts": [
        {
            "id": 4,
            "library_id": 2,
            "name": "music_search",
            "current_ai_prompt_version_id": 7,
            "created_at": "2024-08-19T13:30:26.166-05:00",
            "updated_at": "2026-09-20T09:12:40.101-05:00",
            "prompt": "You turn a request for music into a search of this catalog. The genres are:  ...",
            "metadata_types": ["genre", "mood", "instrument"],
            "ai_search_examples_count": 12,
            "url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/4",
            "ai_prompt_versions_url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/4/ai_prompt_versions",
            "ai_search_examples_url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/4/ai_search_examples"
        },
        {
            "id": 5,
            "library_id": 2,
            "name": "sync_briefs",
            "current_ai_prompt_version_id": 9,
            "created_at": "2026-09-01T15:02:11.410-05:00",
            "updated_at": "2026-09-01T15:02:11.410-05:00",
            "prompt": "The request is a brief from a music supervisor ...",
            "metadata_types": ["genre", "mood"],
            "ai_search_examples_count": 4,
            "url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/5",
            "ai_prompt_versions_url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/5/ai_prompt_versions",
            "ai_search_examples_url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/5/ai_search_examples"
        }
    ]
}

Response Fields

Field	Type	Description
pagination	object	Contains pagination information
ai_prompts	array	List of prompt objects
id	integer	ID of the prompt
library_id	integer	ID of the library
name	string	Name of the prompt. This is what `ai_prompt_name` takes when creating a search.
current_ai_prompt_version_id	integer \| null	ID of the version in use. This is what `ai_prompt_version_id` takes when creating a search.
created_at	string	Timestamp of when the prompt was created
updated_at	string	Timestamp of when the prompt was last updated
prompt	string \| null	Text of the version in use, as it was written, with its ``
metadata_types	array	Names of the tag types whose tags are given to the model. A type with more than 300 tags is listed as its 40 most-used with a note that the rest exist; the model’s name for a tag is matched to the nearest, so the prompt need not list them all.
ai_search_examples_count	integer	Number of examples
url	string	URL of the prompt
ai_prompt_versions_url	string	URL of the prompt’s versions
ai_search_examples_url	string	URL of the prompt’s examples

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID

POST /api/v1/libraries/{library_id}/ai_prompts

Create a prompt. Left out, the text starts as a prompt written from the library’s fields, and the tag types default to every tag type in the library.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Request Body

Wrap the fields in an ai_prompt key.

Field	Type	Description	Required
name	string	Name of the prompt (max 100 chars), unique in the library	Yes
prompt	string	What the prompt says (max 10000 chars). Left out, it starts as one written from the library’s fields.	No
change_note	string	What changed, kept with the new version (max 255 chars)	No
metadata_type_names	array	Names of the tag types whose tags the prompt may include. Every tag type, unless given. Names that are not tag types of the library are dropped.	No

{ "ai_prompt": { "name": "main", "metadata_type_names": ["genre", "mood"] } }

Response

Returns the prompt as GET of one prompt shows it, with a Location header.

HTTP Response Codes

Code	Description
`201 Created`	Successful creation
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID
`422 Unprocessable Content`	Invalid request (see response body for details)

GET /api/v1/libraries/{library_id}/ai_prompts/{id}

Retrieve a prompt, with the text as the model sees it and what is wrong with it.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	ID of the prompt	Yes

Response

The prompt as shown in the list response, with two more fields:

{
    "id": 4,
    "library_id": 2,
    "name": "music_search",
    "current_ai_prompt_version_id": 7,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2026-09-20T09:12:40.101-05:00",
    "prompt": "You turn a request for music into a search of this catalog. The genres are:  ...",
    "metadata_types": ["genre", "mood", "instrument"],
    "ai_search_examples_count": 12,
    "url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/4",
    "ai_prompt_versions_url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/4/ai_prompt_versions",
    "ai_search_examples_url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/4/ai_search_examples",
    "full_prompt": "You turn a request for music into a search of this catalog. The genres are: rock, pop, jazz, classical, ...",
    "lint": [
        {
            "severity": "error",
            "subject": "example",
            "message": "\"orchestration\" is not a field of this library.",
            "example_id": 61
        }
    ]
}

Field	Type	Description
full_prompt	string \| null	The text as the model sees it, with the library’s metadata filled in. Null when the prompt has no version yet.
lint	array	What the search cannot use in the prompt and its examples; empty when there is nothing. Each costs the model a second attempt at every search.
severity	string	`error` or `warning`
subject	string	`prompt` or `example`
message	string	What is wrong, and often what was meant
example_id	integer \| null	The example at fault, when it is one

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID or prompt ID

PUT /api/v1/libraries/{library_id}/ai_prompts/{id}

Change a prompt. PATCH works the same way. The body takes the same fields as create.

A prompt that differs from what the prompt says now makes a new version, whose parent is the current one, and makes it current; change_note is kept with it. name and metadata_type_names change in place and make no version.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	ID of the prompt	Yes

Request Body

{ "ai_prompt": { "prompt": "You turn a request for music into a search ...", "change_note": "Say what a boost is for" } }

Response

Returns the updated prompt as GET of one prompt shows it.

HTTP Response Codes

Code	Description
`200 OK`	Successful update
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID or prompt ID
`422 Unprocessable Content`	Invalid request (see response body for details)

DELETE /api/v1/libraries/{library_id}/ai_prompts/{id}

Delete a prompt. Its versions and examples go with it.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	ID of the prompt	Yes

Response

(no response body)

HTTP Response Codes

Code	Description
`204 No Content`	Successful deletion
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID or prompt ID

POST /api/v1/libraries/{library_id}/ai_prompts/{id}/copy

Make a new prompt with this one’s text, tag types and examples. The way to try a change without touching the prompt in use: copy it, change the copy, and search with ai_prompt_name set to the copy.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	ID of the prompt to copy	Yes

Request Body

Not wrapped, and optional.

Field	Type	Description	Required
name	string	Name of the new prompt. Default: the other’s name with “ copy” after it.	No

{ "name": "experiment" }

Response

Returns the new prompt as GET of one prompt shows it, with a Location header.

HTTP Response Codes

Code	Description
`201 Created`	The copy was made
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID or prompt ID
`422 Unprocessable Content`	Invalid request, such as a name already in use

Versions

Every change to a prompt’s text makes a version, with its parent. An older version can be made current again, and a version that is not current can be removed. Not paged.

GET /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_prompt_versions

Retrieve the prompt’s versions, oldest first.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
ai_prompt_id	integer	ID of the prompt	Yes

Response

{
    "ai_prompt_versions": [
        {
            "id": 33,
            "ai_prompt_id": 7,
            "parent_ai_prompt_version_id": null,
            "change_note": null,
            "created_at": "2026-09-01T15:02:11.410-05:00",
            "updated_at": "2026-09-01T15:02:11.410-05:00",
            "current": false,
            "url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/7/ai_prompt_versions/33"
        },
        {
            "id": 34,
            "ai_prompt_id": 7,
            "parent_ai_prompt_version_id": 33,
            "change_note": "Say what a boost is for",
            "created_at": "2026-09-16T11:37:13.574-05:00",
            "updated_at": "2026-09-16T11:37:13.574-05:00",
            "current": true,
            "url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/7/ai_prompt_versions/34"
        }
    ]
}

Response Fields

Field	Type	Description
id	integer	ID of the version. This is what `ai_prompt_version_id` takes when creating a search.
ai_prompt_id	integer	ID of the prompt
parent_ai_prompt_version_id	integer \| null	The version this one was made from; null for a first version
change_note	string \| null	What changed
created_at, updated_at	string	Timestamps
current	boolean	Whether this is the version in use
url	string	URL of the version

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID or prompt ID

GET /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_prompt_versions/{id}

Retrieve a version with its text and the diff from its parent.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
ai_prompt_id	integer	ID of the prompt	Yes
id	integer	ID of the version	Yes

Response

The version as shown in the list response, with two more fields:

{
    "id": 34,
    "ai_prompt_id": 7,
    "parent_ai_prompt_version_id": 33,
    "change_note": "Say what a boost is for",
    "created_at": "2026-09-16T11:37:13.574-05:00",
    "updated_at": "2026-09-16T11:37:13.574-05:00",
    "current": true,
    "url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/7/ai_prompt_versions/34",
    "prompt": "You turn a request for music into a search ...",
    "diff": " Artist Queries:\n-* Use the \"similar_artists\" field ...\n+* Use the \"style_alikes\" field ...\n"
}

Field	Type	Description
prompt	string	The text of this version
diff	string \| null	A unified diff from the parent, with two lines of context; null for a first version

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID, prompt ID or version ID

POST /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_prompt_versions/{id}/make_current

Make this version the one in use. No body.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
ai_prompt_id	integer	ID of the prompt	Yes
id	integer	ID of the version	Yes

Response

Returns the version as GET of one version shows it.

HTTP Response Codes

Code	Description
`200 OK`	The version is now current
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID, prompt ID or version ID

DELETE /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_prompt_versions/{id}

Remove a version that is not current.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
ai_prompt_id	integer	ID of the prompt	Yes
id	integer	ID of the version	Yes

Response

(no response body)

HTTP Response Codes

Code	Description
`204 No Content`	Successful deletion
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID, prompt ID or version ID
`422 Unprocessable Content`	`{ "base": ["The current version of a prompt can't be removed; make another version current first"] }`

Examples

The worked examples sent with a prompt have endpoints of their own.