> ## Documentation Index > Fetch the complete documentation index at: https://docs.poelis.com/llms.txt > Use this file to discover all available pages before exploring further. # Create item > Create a new item in a product. The item will be created with the provided name and readable_id. If parent_item_id is provided, the item will be created as a child of that item. Optional `part_number` is validated when the product has format configuration in the app. ## Part numbers - **409**: duplicate `part_number` within the organization (response includes conflicting entity details). - **422**: value does not match the product's configured format. ## OpenAPI ````yaml /openapi.json post /v1/public/items openapi: 3.1.0 info: title: Poelis Public API description: |2- Poelis Public API - REST endpoints for external clients and integrations. ## Authentication All endpoints require an API key in the `Authorization` header: ``` Authorization: Bearer poelis_api_... ``` Get your API key from the web application's API Keys section. ## Rate Limiting API requests are rate-limited per organization. Contact support for higher limits. ## Support For questions or issues, contact support@poelis.com version: 1.0.0 servers: - url: https://api.poelis.com description: Production - url: http://localhost:8000 description: Local security: [] paths: /v1/public/items: post: tags: - Items summary: Create item description: |- Create a new item in a product. The item will be created with the provided name and readable_id. If parent_item_id is provided, the item will be created as a child of that item. Optional `part_number` is validated when the product has format configuration in the app. ## Part numbers - **409**: duplicate `part_number` within the organization (response includes conflicting entity details). - **422**: value does not match the product's configured format. operationId: create_item_v1_public_items_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateItemRequest' responses: '201': description: Created item content: application/json: schema: $ref: '#/components/schemas/PublicItem' headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' '400': description: Bad Request headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' '401': description: Unauthorized - Invalid or missing API key headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: unauthorized message: Invalid or missing API key '403': description: Forbidden - Access denied headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: forbidden message: Access denied '404': description: Not found headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: not_found message: Not found '409': description: Conflict - duplicate readable_id or part number headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' '422': description: Validation error - Invalid request body or parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: validation_error message: Invalid data format details: errors: - loc: - body - field_name msg: field required type: value_error.missing '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate_limit_exceeded message: Too many requests security: - API Key: [] components: schemas: CreateItemRequest: properties: product_id: type: string title: Product Id description: Product ID to create the item in name: type: string minLength: 1 title: Name description: Item name description: anyOf: - type: string - type: 'null' title: Description description: Item description part_number: anyOf: - type: string - type: 'null' title: Part Number description: >- Optional part number to assign on create. Must be unique within the organization. readable_id: type: string minLength: 1 pattern: ^[a-z0-9_]+$ title: Readable Id description: >- Human-readable item ID (must be unique within parent scope). Only lowercase letters, numbers and underscores are allowed. parent_item_id: anyOf: - type: string - type: 'null' title: Parent Item Id description: Parent item ID for hierarchical structure type: object required: - product_id - name - readable_id title: CreateItemRequest description: Request to create a new item. PublicItem: properties: id: type: string title: Id readable_id: type: string title: Readable Id description: Human-readable item ID product_id: type: string title: Product Id description: Product this item belongs to parent_item_id: anyOf: - type: string - type: 'null' title: Parent Item Id description: Parent item ID for hierarchical structure name: type: string title: Name description: Item name description: anyOf: - type: string - type: 'null' title: Description description: Item description part_number: anyOf: - type: string - type: 'null' title: Part Number description: >- Active item part number, when assigned. Uniqueness is enforced organization-wide; format is validated when the product has rule configuration in the app. draft_item_id: anyOf: - type: string - type: 'null' title: Draft Item Id description: Draft item ID if this is a versioned item deleted: type: boolean title: Deleted description: Whether the item is deleted createdBy: anyOf: - $ref: '#/components/schemas/PublicUser' - type: 'null' description: User who created the item createdAt: anyOf: - type: string - type: 'null' title: Createdat description: ISO 8601 creation timestamp updatedAt: anyOf: - type: string - type: 'null' title: Updatedat description: ISO 8601 last-update timestamp updatedBy: anyOf: - $ref: '#/components/schemas/PublicUser' - type: 'null' description: User who last updated the item type: object required: - id - readable_id - product_id - name - deleted title: PublicItem description: Public representation of an item. examples: - createdBy: id: auth0|550e8400-e29b-41d4-a716-446655440000 imageUrl: https://example.com/avatar.png userName: Jane Doe deleted: false id: 770e8400-e29b-41d4-a716-446655440000 name: Compressor Stage 1 part_number: CS1-001 product_id: 660e8400-e29b-41d4-a716-446655440000 readable_id: compressor-stage-1 - createdBy: id: auth0|550e8400-e29b-41d4-a716-446655440000 imageUrl: https://example.com/avatar.png userName: Jane Doe deleted: false draft_item_id: 880e8400-e29b-41d4-a716-446655440002 id: 770e8400-e29b-41d4-a716-446655440001 name: Rotor Blade parent_item_id: 770e8400-e29b-41d4-a716-446655440000 product_id: 660e8400-e29b-41d4-a716-446655440000 readable_id: rotor-blade ErrorResponse: type: object properties: error: type: string description: Machine-readable error code (e.g. validation_error, item_not_found). message: type: string description: Human-readable error message. details: type: object description: >- Additional error context (optional). For validation errors, contains a list of field-level issues. nullable: true required: - error - message PublicUser: properties: id: type: string title: Id description: User ID userName: type: string title: Username description: Display name imageUrl: anyOf: - type: string - type: 'null' title: Imageurl description: Avatar URL type: object required: - id - userName title: PublicUser description: >- User representation in public API responses (owner, createdBy, updatedBy). example: id: auth0|550e8400-e29b-41d4-a716-446655440000 imageUrl: https://example.com/avatar.png userName: Jane Doe headers: RequestId: description: >- Request correlation ID. Echoes the incoming `x-request-id` header or a server-generated ID. schema: type: string RateLimitLimit: description: Request limit for the current rate limit window. schema: type: integer RateLimitRemaining: description: Remaining requests in the current rate limit window. schema: type: integer RateLimitReset: description: Unix timestamp (seconds) when the current rate limit window resets. schema: type: integer securitySchemes: API Key: type: http scheme: bearer bearerFormat: API Key description: 'Enter your API key. Example: Bearer poelis_api_...' ````