> ## Documentation Index > Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt > Use this file to discover all available pages before exploring further. # Add books to portfolios and optionally share them. > Creates each requested book beneath its named parent portfolios and can grant edit access to invited users. Parent portfolios must be available and editable by the caller. Requests are handled item by item: a valid book can be created when another item fails, and a sharing failure can follow book creation. Reconcile `IsSuccess` and every error message; an unsuccessful aggregate result is not a rollback. This is a synchronous mutation. ## OpenAPI ````yaml /risk-and-pricing/atoti-risk-services/apis-endpoints/openapi/openapi.mintlify.json post /api/Position/CreateBooks openapi: 3.0.4 info: title: Derivitec Api 1.0 version: '1.0' servers: - url: https://api.riskportal.activeviam.com security: - oauth2: [] - apikey: [] tags: - name: AdminUser - name: AtotiReport - name: AtotiSession - name: BloombergOAuth - name: Bond - name: BondYieldCurvePage - name: BookAccess - name: Books - name: Commodity - name: Counterparties - name: Currencies - name: Equity - name: EquityDividend - name: EquityPage - name: FeatureFlag - name: Fx - name: FxPage - name: GroupAccess - name: Home - name: LegacyPosition - name: MarketData - name: MarketDataProvider - name: MarketDataProviderAccess - name: Meta - name: Notification - name: Organisation - name: PnLReport - name: PortfolioAccess - name: Portfolios - name: Position - name: PositionFilter - name: PricingEnvironment - name: PricingEnvironmentAccess - name: RateAsset - name: RateAssetPage - name: Report - name: ReportDefinition - name: ReportHistoryLauncherQuery - name: ReportLauncher - name: ReportQuery - name: ReportQueryViewUser - name: ReportRestriction - name: ReportView - name: RiskReport - name: Tradable - name: TradeBooking - name: User - name: VarReport - name: VarReportQuery - name: YieldCurvePage paths: /api/Position/CreateBooks: post: tags: - Position summary: Add books to portfolios and optionally share them. description: >- Creates each requested book beneath its named parent portfolios and can grant edit access to invited users. Parent portfolios must be available and editable by the caller. Requests are handled item by item: a valid book can be created when another item fails, and a sharing failure can follow book creation. Reconcile `IsSuccess` and every error message; an unsuccessful aggregate result is not a rollback. This is a synchronous mutation. operationId: CreateBooks requestBody: description: >- JSON request with non-null `CreateBookRequests`. Each item has a `Name` and `Description` of 2–100 characters, non-null `ParentPortfolioNames`, and non-null `SharedUsers` (which may be empty). A shared-user value must contain `@`. content: application/json-patch+json: schema: $ref: '#/components/schemas/ApiCreateBooksRequest' application/json: schema: $ref: '#/components/schemas/ApiCreateBooksRequest' text/json: schema: $ref: '#/components/schemas/ApiCreateBooksRequest' application/*+json: schema: $ref: '#/components/schemas/ApiCreateBooksRequest' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ApiBaseResponseEnvelope' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Unauthorized '403': description: Forbidden default: description: Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' security: - oauth2: [] - apikey: [] components: schemas: ApiCreateBooksRequest: required: - $type type: object properties: create_book_requests: type: array items: $ref: '#/components/schemas/ApiCreateBookRequest' description: >- Book definitions, parent links, and sharing requests to process in order. nullable: true $type: type: string enum: - >- Derivitec.Web.Core.Positions.ApiCreateBooksRequest, Derivitec.Web.Core additionalProperties: false description: >- Batch of books created item by item, allowing earlier successful items to remain when another item fails. ApiBaseResponseEnvelope: required: - $type type: object properties: is_success: type: boolean description: >- Whether the operation completed successfully. The default is `true`; error outcomes set it to `false`. example: true error_messages: type: array items: type: string description: >- Messages explaining operation-level failures. The collection is empty by default. nullable: true $type: type: string enum: - Derivitec.Web.Core.ApiBaseResponse, Derivitec.Web.Core additionalProperties: false description: >- Common operation outcome containing a success indicator and any error messages. example: $type: Derivitec.Web.Core.ApiBaseResponse, Derivitec.Web.Core is_success: true error_messages: [] ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: false ApiCreateBookRequest: required: - $type - description - name type: object properties: description: maxLength: 100 minLength: 2 type: string description: Book description; validation accepts from 2 through 100 characters. name: maxLength: 100 minLength: 2 type: string description: Book name; validation accepts from 2 through 100 characters. parent_portfolio_names: type: array items: type: string description: >- Names of editable portfolios that will become direct parents of the new book. nullable: true shared_users: type: array items: type: string description: >- User email addresses requested for edit access after the book is created. nullable: true $type: type: string enum: - >- Derivitec.Web.Core.Positions.ApiCreateBookRequest, Derivitec.Web.Core additionalProperties: false description: >- One book to create, its parent portfolios, and existing users requested for edit access. securitySchemes: oauth2: type: oauth2 description: >- OAuth2 access-token requested from AWS Cognito and provided as a Auth Bearer header flows: implicit: authorizationUrl: https://auth.riskportal.derivitec.com/oauth2/authorize scopes: {} apikey: type: apiKey description: API-Key requested via the site and provided as a header name: x-api-key in: header ````