> ## 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. # Update item > Update an item's metadata (name, description, readable_id, parent_item_id). Only draft items can be updated. Only fields provided in the request will be updated. ## Part numbers `part_number` supports assign/remove only: pass a string to assign when empty, or `null` to remove (retire) the current one. Changing to a different string without removing first returns **422** (`PART_NUMBER_ALREADY_ASSIGNED`). ## OpenAPI ````yaml /openapi.json patch /v1/public/items/{item_id} 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/{item_id}: patch: tags: - Items summary: Update item description: >- Update an item's metadata (name, description, readable_id, parent_item_id). Only draft items can be updated. Only fields provided in the request will be updated. ## Part numbers `part_number` supports assign/remove only: pass a string to assign when empty, or `null` to remove (retire) the current one. Changing to a different string without removing first returns **422** (`PART_NUMBER_ALREADY_ASSIGNED`). operationId: update_item_v1_public_items__item_id__patch parameters: - name: item_id in: path required: true schema: type: string title: Item Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateItemRequest' responses: '200': description: Updated 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: UpdateItemRequest: properties: name: anyOf: - type: string minLength: 1 - type: 'null' 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: >- Assign a part number when the draft item has none, or pass null to remove (retire) the current one. Must be unique within the organization. readable_id: anyOf: - type: string minLength: 1 pattern: ^[a-z0-9_]+$ - type: 'null' 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 title: UpdateItemRequest description: Request to update an 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_...' ````