Managing the Active Library

Every API call in Apicbase operates in the context of a single library. That library is called the active library, and it is a persistent setting stored on the user account. It does not change between requests unless you explicitly switch it.

All data returned by the API, such as recipes, ingredients, outlets, inventory, procurement, belongs to the active library. When you switch the active library, all subsequent API calls will operate on the new library's data.

📘

For a broader discussion of multi-library strategies, including the recommended service account token approach, see Working with Multiple Libraries.

Listing Available Libraries

Use the Get Libraries endpoint to retrieve all libraries the current user has access to. The response includes each library's id, name, and status. Blocked libraries appear in this list but cannot be set as the active library.

Call this endpoint once at startup to discover and store the available library IDs.

Checking the Active Library

Use the Get Active Library endpoint to retrieve the library currently active for the authenticated user. The response includes the library's id, name, and status, along with the connected user's details.

This is useful for confirming the correct library context before making requests, or for displaying the current library in your application's UI.

Switching the Active Library

Use the Switch Active Library endpoint to change the active library. Pass the target library's id in the request body:

{
  "library_id": 12345
}

The switch takes effect immediately. All API calls made after a successful switch will operate on the new library's data. The operation is idempotent: if the specified library is already active, the endpoint returns the current state without making any changes.

Note that outlet users cannot switch libraries.

Typical Multi-Library Flow

If your integration needs to operate across more than one library using a personal token:

1. Call Get Libraries once and store the returned library IDs.
2. Call Switch Active Library before any operation targeting a specific library.
3. Proceed with your requests. They will be scoped to the newly active library.

Be aware that the active library is a property of the user account, not of the token or the session. If the same user account is active in the Apicbase UI at the same time, switching libraries via the API will affect their UI context as well.