Collaborators API Documentation

Who may use a library, and as what. Every collaborator has a role, from least to most privileged:

Role May
viewer Read and search
editor Also change the catalog, prompts and examples
admin Also change the library’s settings, its AI providers and who may use it
owner The one the library belongs to. One per library, and cannot be changed or removed here.

A collaborator is addressed by the user’s ID. Any collaborator may read; changing takes the admin role and the catalog_admin scope. There is no POST: people join a library by invitation, which is sent from the site.

Endpoints

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

Retrieve everyone who may use the library, by role. Not paged.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes

Response

{
    "collaborators": [
        {
            "id": 9,
            "name": "Floyd Lawson",
            "email": "[email protected]",
            "role": "owner",
            "created_at": "2026-09-16T10:54:16.878-05:00",
            "updated_at": "2026-09-16T10:54:16.878-05:00",
            "url": "https://app.spondulix.ai/api/v1/libraries/2/collaborators/9"
        },
        {
            "id": 14,
            "name": "Barney Fife",
            "email": "[email protected]",
            "role": "editor",
            "created_at": "2026-09-29T15:20:41.002-05:00",
            "updated_at": "2026-09-29T15:20:41.002-05:00",
            "url": "https://app.spondulix.ai/api/v1/libraries/2/collaborators/14"
        }
    ],
    "assignable_roles": ["admin", "editor", "viewer"]
}

Response Fields

Field Type Description
collaborators array The library’s collaborators
id integer ID of the user, which is what addresses the collaborator
name string Name of the user
email string Email address of the user
role string owner, admin, editor or viewer
created_at string Timestamp of when the user joined the library
updated_at string Timestamp of when the role last changed
url string URL of the collaborator
assignable_roles array The roles a collaborator can be given

HTTP Response Codes

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

GET /api/v1/libraries/{library_id}/collaborators/{user_id}

Retrieve one collaborator.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
user_id integer ID of the user Yes

Response

Returns the collaborator as shown in the list response.

HTTP Response Codes

Code Description
200 OK Successful request
404 Not Found Invalid library ID, or the user is not a collaborator

PUT /api/v1/libraries/{library_id}/collaborators/{user_id}

Change a collaborator’s role. PATCH works the same way. The owner’s role cannot be changed.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
user_id integer ID of the user Yes

Request Body

Wrap the field in a collaborator key.

Field Type Description Required
role string admin, editor or viewer Yes 
{ "collaborator": { "role": "admin" } }

Response

Returns the updated collaborator.

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 Invalid library ID, or the user is not a collaborator
422 Unprocessable Content { "role": ["must be one of admin, editor, viewer"] }, or { "role": ["Cannot change the owner's role"] }

DELETE /api/v1/libraries/{library_id}/collaborators/{user_id}

Remove a collaborator from the library. The owner cannot be removed.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
user_id integer ID of the user Yes

Response

(no response body)

HTTP Response Codes

Code Description
204 No Content Successful removal
403 Forbidden Your role is below admin, or the token does not carry catalog_admin
404 Not Found Invalid library ID, or the user is not a collaborator
422 Unprocessable Content { "base": ["The owner of a library cannot be removed from it"] }