Examples API Documentation

A prompt is sent with worked examples: each a request in natural language and the answer the model should give for it. They are how the model learns a catalog’s vocabulary. An example that is hidden is kept and not sent.

The quickest way to a good example is a search that read a request well, kept with POST .../searches/{id}/save_as_example. The model can also suggest requests of its own, below. Reading is open to every collaborator; changing takes the editor role and the catalog_write scope.

Endpoints

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

Retrieve the prompt’s examples, in order.

Path Parameters

Query Parameters

Response

{
    "pagination": {
        "total_entries": 12,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 1
    },
    "ai_search_examples": [
        {
            "id": 31,
            "ai_prompt_id": 4,
            "user_query": "upbeat rock songs about the open road",
            "example_struct": {
                "query": {
                    "filter": { "genre": { "value": "rock" } },
                    "boost": {
                        "mood": { "value": "upbeat", "weight": 50 },
                        "lyrical_theme": { "value": "driving on the open road", "weight": 40 }
                    }
                }
            },
            "position": 1,
            "active": true,
            "created_at": "2024-08-19T13:30:26.166-05:00",
            "updated_at": "2024-08-19T13:30:26.166-05:00",
            "url": "https://app.spondulix.ai/api/v1/libraries/2/ai_prompts/4/ai_search_examples/31"
        }
    ]
}

Response Fields

HTTP Response Codes

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

Create an example.

Path Parameters

Request Body

Wrap the fields in an ai_search_example key.

{
    "ai_search_example": {
        "user_query": "upbeat rock songs about the open road",
        "example_struct": { "query": { "filter": { "genre": { "value": "rock" } } } }
    }
}

Response

Returns the example as shown in the list response, with a Location header.

HTTP Response Codes

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

Retrieve an example.

Path Parameters

Response

Returns the example as shown in the list response.

HTTP Response Codes

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

Change an example. PATCH works the same way, and only the fields you send change. The body takes the same fields as create.

Path Parameters

Response

Returns the updated example.

HTTP Response Codes

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

Delete an example.

Path Parameters

Response

(no response body)

HTTP Response Codes

POST /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_search_examples/{id}/hide

Stop sending the example with the prompt, keeping it. No body.

Path Parameters

Response

Returns the example, with active false.

HTTP Response Codes

POST /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_search_examples/{id}/unhide

Send a hidden example with the prompt again. No body.

Path Parameters

Response

Returns the example, with active true.

HTTP Response Codes

POST /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_search_examples/sort

Put the examples in order in one request. An example left out keeps its position.

Path Parameters

Request Body

{ "ai_search_example": [40, 31, 35] }

Response

(no response body)

HTTP Response Codes

POST /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_search_examples/suggest

Have the model write requests that someone might make of the library, and run each as a search in the background. The request is answered at once; the searches appear under suggested as they finish, to be kept or thrown away.

This costs money: one call to the library’s AI provider to write the requests, and then a search for each of them, each charged to the library’s AI account as any search is.

Path Parameters

Request Body

Not wrapped, and both fields optional.

{ "count": 5, "focus": "trailer editors" }

Response

{
    "searches": [
        { "id": 230, "nls": "cinematic atmospheric trailer like two steps from hell", "url": "https://app.spondulix.ai/api/v1/libraries/2/searches/230" }
    ]
}

HTTP Response Codes

GET /api/v1/libraries/{library_id}/ai_prompts/{ai_prompt_id}/ai_search_examples/suggested

Retrieve the suggested searches that wait to be kept or thrown away. A suggestion is kept as an example with POST .../searches/{id}/save_as_example and thrown away with DELETE .../searches/{id}; either takes it off this list.

Path Parameters

Response

{
    "suggestions": [
        {
            "search_id": 230,
            "nls": "cinematic atmospheric trailer like two steps from hell",
            "status": "answered",
            "error_message": null,
            "explanation": "This query filters for atmospheric cinematic music ...",
            "total_rows": 0,
            "top_titles": [],
            "answer": { "explanation": "...", "query": { "filter": {}, "boost": [] } },
            "url": "https://app.spondulix.ai/api/v1/libraries/2/searches/230"
        }
    ]
}

Response Fields

HTTP Response Codes