Using REST API - Create Libraries

The create library API ({your_mart_url}/MartServer/api/catalog/library/create) enables you to create libraries using an external tool such as Postman. You only have to provide the library name, an optional description, and the ID of the parent container (Mart or Library). All other internal fields are generated automatically by the backend.

To move catalogs, ensure that you have:

  • View permissions on the model hierarchy
  • Delete permissions at the source location (current container)
  • Create permissions at the target location (new container)

Endpoint Information

Property Value
Method POST
URL /MartServer/api/catalog/library/create
Authentication Required (Bearer Token)
Content-Type application/json

Creating Libraries

Step 1: Create a New Request

  1. Open Postman and click New > HTTP Request.

  2. Set the method to POST.

  3. Enter the URL: https://<your-server-host>:<port>/MartServer/api/catalog/library/create.

    Example: https://localhost:8443/MartServer/api/catalog/library/create.

Step 2: Configure Authentication

  1. Generate an API Access Token from the erwin Mart Portal:

    1. Navigate to Settings > API Access Tokens.

    2. Create a new token or copy an existing one.

  2. Go to the Authorization tab.

  3. Select Bearer Token as the type.

  4. Paste the API Access Token into the Token field.

Step 3: Configure the Header

  1. Go to the Headers tab.

  2. Ensure that the Content-Type is set to application/json.

Step 4: Configure the Request Body

  1. Go to the Body tab

  2. Select raw and choose JSON from the dropdown

  3. Enter the request payload:

    For example:

    {
"name": "My New Library",
"description": "Created via Postman",
"containerId": 1
}

Request Parameters

The request body must be a JSON object containing the following fields:

Parameter Type Required Max Length Constraints Description
name String Yes 255 Non-blank after trimming; must not contain< > ~ { } | The name of the library to create
description String No 4000 — Optional description for the library (defaults to empty string)
containerId Integer Yes — Positive integer; must reference an existing Mart or Library The ID of the parent container where the library will be created

Step 5: Send the Request

Click Send. The response will be a JSON object indicating success or failure.

Response Reference

Success Response (HTTP 200) 

{
"success": true,
"message": "Library created successfully",
"data": 
{
"catalogId": 42,
"name": "My New Library"
}
}

Error Responses

HTTP Code Error Scenario Example Response
400 Invalid name (blank, too long, or contains forbidden characters) {"error": "Library name must not be blank"}
400 Description exceeds 4000 characters {"error": "Description exceeds maximum length"}
400 Invalid or missingcontainerId {"error": "containerId must be a positive integer"}
401 Missing or invalid authentication token {"error": "Unauthorized: No valid token provided"}
403 User lacks permission to create library {"error": "Forbidden: User does not have permission to create a library"}
404 Container with specifiedcontainerIdnot found {"error": "Container not found"}
500 Internal server error (database failure, etc.) {"error": "Failed to create library: <error details>"}