Libraries API Documentation

A library is a catalog with its own tracks, metadata, prompts, AI provider keys and collaborators. The API lists the libraries your account owns or collaborates on, makes new ones, and changes a library’s settings. Deleting a library is left to the site: DELETE /api/v1/libraries/{id} is 404.

Endpoints

GET /api/v1/libraries

Retrieve the libraries your token can access, ordered by name.

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
    },
    "libraries": [
        {
            "id": 1,
            "name": "Classical Collection",
            "description": "A comprehensive collection of classical music",
            "chat_provider": "openai",
            "chat_model": "gpt-4o",
            "embedding_provider": "openai",
            "embedding_model": "text-embedding-3-large",
            "created_at": "2024-08-19T13:30:26.166-05:00",
            "updated_at": "2024-08-19T13:36:56.251-05:00",
            "role": "owner",
            "tracks_count": 22148,
            "ai_prompts_count": 3,
            "url": "https://app.spondulix.ai/api/v1/libraries/1"
        },
        {
            "id": 2,
            "name": "Modern Compositions",
            "description": "Contemporary classical and experimental works",
            "chat_provider": "openai",
            "chat_model": "gpt-4o",
            "embedding_provider": null,
            "embedding_model": null,
            "created_at": "2024-08-19T13:30:26.166-05:00",
            "updated_at": "2024-08-19T13:36:56.251-05:00",
            "role": "viewer",
            "tracks_count": 1581,
            "ai_prompts_count": 0,
            "url": "https://app.spondulix.ai/api/v1/libraries/2"
        }
    ]
}

Response Fields

Field	Type	Description
pagination	object	Contains pagination information
libraries	array	List of library objects
id	integer	Unique identifier for the library
name	string	Name of the library
description	string \| null	Description of the library’s contents
chat_provider	string \| null	AI provider that searches use unless they name another
chat_model	string \| null	Chat model that searches use unless they name another
embedding_provider	string \| null	AI provider that embeds lyrics
embedding_model	string \| null	Model that embeds lyrics
created_at	string	Timestamp of when the library was created
updated_at	string	Timestamp of when the library was last updated
role	string	What you may do in the library: `owner`, `admin`, `editor` or `viewer`. Changing the catalog takes `editor` or above; changing the library’s settings, providers and collaborators takes `admin` or above.
tracks_count	integer	Number of tracks in the library
ai_prompts_count	integer	Number of prompts. A library with none cannot be searched in natural language.
url	string	URL of the library

HTTP Response Codes

Code	Description
`200 OK`	Successful request

POST /api/v1/libraries

Make a library. Anyone may; the caller becomes its owner. Takes the catalog_admin scope.

Request Body

Wrap the fields in a library key.

Field	Type	Description	Required
name	string	Name of the library (max 100 chars)	Yes
description	string	What it holds (max 1000 chars)	No
chat_provider	string	AI provider that searches use. The library must hold a key for it, which a new library does not: set this afterwards.	No
chat_model	string	Chat model that searches use. One the provider offers; see models.	With `chat_provider`
embedding_provider	string	AI provider that embeds lyrics	No
embedding_model	string	Model that embeds lyrics	With `embedding_provider`

{ "library": { "name": "Frivolous Music", "description": "Production music for film and television" } }

Response

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

HTTP Response Codes

Code	Description
`201 Created`	Successful creation
`403 Forbidden`	The token does not carry `catalog_admin`
`422 Unprocessable Content`	Invalid request (see below)

GET /api/v1/libraries/{id}

Retrieve a library. Unlike the list, it carries the owner.

Path Parameters

Name	Type	Description	Required
id	integer	ID of the library	Yes

Response

{
    "id": 1,
    "name": "Classical Collection",
    "description": "A comprehensive collection of classical music",
    "chat_provider": "openai",
    "chat_model": "gpt-4o",
    "embedding_provider": "openai",
    "embedding_model": "text-embedding-3-large",
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-19T13:36:56.251-05:00",
    "role": "owner",
    "tracks_count": 22148,
    "ai_prompts_count": 3,
    "url": "https://app.spondulix.ai/api/v1/libraries/1",
    "owner": { "id": 9, "name": "Floyd Lawson", "email": "[email protected]" }
}

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Unknown library, or a library you do not collaborate on

PUT /api/v1/libraries/{id}

Change a library’s settings. PATCH works the same way, and only the fields you send change. Takes the admin role and the catalog_admin scope.

Path Parameters

Name	Type	Description	Required
id	integer	ID of the library	Yes

Request Body

The same fields as create, wrapped in library.

{
    "library": {
        "chat_provider": "openai",
        "chat_model": "gpt-4o",
        "embedding_provider": "openai",
        "embedding_model": "text-embedding-3-large"
    }
}

Response

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

HTTP Response Codes

Code	Description
`200 OK`	Successful update
`403 Forbidden`	Your role is below admin, or the token does not carry `catalog_admin`
`404 Not Found`	Unknown library, or a library you do not collaborate on
`422 Unprocessable Content`	Invalid request (see below)

The 422 bodies a client meets when setting models:

{ "chat_provider": ["has no credentials configured for this library"] }
{ "chat_provider": ["is not a known provider"] }
{ "chat_model": ["is not offered by openai"] }
{ "chat_model": ["can't be blank"] }
{ "chat_model": ["requires a provider"] }

GET /api/v1/libraries/{id}/models

Retrieve what each provider the library holds a key for can use, and the library’s four settings, so a client can set them validly. Any collaborator may.

The lists are fetched from the provider with the library’s key, and are long; a provider that cannot be reached shows the models the application knows of.

Path Parameters

Name	Type	Description	Required
id	integer	ID of the library	Yes

Response

{
    "providers": [
        {
            "provider": "openai",
            "display_name": "OpenAI",
            "chat_models": ["gpt-4o", "gpt-4o-mini"],
            "embedding_models": ["text-embedding-3-small", "text-embedding-3-large"]
        }
    ],
    "chat_provider": "openai",
    "chat_model": "gpt-4o",
    "embedding_provider": "openai",
    "embedding_model": "text-embedding-3-large"
}

Response Fields

Field	Type	Description
providers	array	One entry per provider the library holds a key for
provider	string	Name of the provider
display_name	string	What the provider is called
chat_models	array	Chat models the library’s key can use
embedding_models	array	Embedding models the library’s key can use
chat_provider, chat_model, embedding_provider, embedding_model	string \| null	The library’s settings, as in the library JSON

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Unknown library, or a library you do not collaborate on