> ## Documentation Index > Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add tags to a file > Add one or more tags to a file without affecting existing tags. **Behavior:** - Adds new tags to the document while preserving existing ones - New tags are marked as manually assigned (`auto_assigned=False`) - Duplicate tags are ignored (no error if tag already exists on document) **Validation:** - Returns 400 if tag IDs are invalid or don't belong to user's company - Returns 403 if user doesn't have permission to edit the document - Returns 404 if document doesn't exist ## OpenAPI ````yaml /api-reference/openapi-v3.yaml post /api/v3/files/{id}/tags openapi: 3.0.3 info: title: Paradigm API version: xenial-xerus (v3) description: >- A versatile and adaptable tool designed to integrate Generative AI into your applications servers: - url: https://paradigm.lighton.ai security: [] tags: - name: Agents description: Operations about agents - name: Threads description: Operations about agents conversation threads - name: Tools description: Operations about native tools - name: Models description: Operations about AI models - name: MCP description: Operations about MCP servers - name: Sources description: Operations about sources used by agents conversation threads - name: Artifacts description: Operations about artifacts generated by agents conversation threads - name: Agent description: >- Operations about agents (deprecated). Please use the 'Agents' API component instead. - name: Files description: Operations about files - name: Files Processing description: Operations about files processing - name: Tags description: Operations about tags - name: Workspaces description: Operations about workspaces - name: Users description: Operations about users - name: User Groups description: Operations about user groups - name: Companies description: Operations about companies - name: SCIM description: Operations about SCIM paths: /api/v3/files/{id}/tags: post: tags: - Tags summary: Add tags to a file description: > Add one or more tags to a file without affecting existing tags. **Behavior:** - Adds new tags to the document while preserving existing ones - New tags are marked as manually assigned (`auto_assigned=False`) - Duplicate tags are ignored (no error if tag already exists on document) **Validation:** - Returns 400 if tag IDs are invalid or don't belong to user's company - Returns 403 if user doesn't have permission to edit the document - Returns 404 if document doesn't exist operationId: api_v3_files_tags_create parameters: - in: path name: id schema: type: integer required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/FileTaggingAddRequest' examples: AddSingleTag: value: tags: - 1 summary: Add single tag description: Add one tag to a file AddMultipleTags: value: tags: - 1 - 2 summary: Add multiple tags description: Add multiple tags to a file at once application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/FileTaggingAddRequest' examples: AddSingleTag: value: tags: - 1 summary: Add single tag description: Add one tag to a file AddMultipleTags: value: tags: - 1 - 2 summary: Add multiple tags description: Add multiple tags to a file at once multipart/form-data: schema: $ref: '#/components/schemas/FileTaggingAddRequest' examples: AddSingleTag: value: tags: - 1 summary: Add single tag description: Add one tag to a file AddMultipleTags: value: tags: - 1 - 2 summary: Add multiple tags description: Add multiple tags to a file at once required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileRetrieveResponseSerializerV3' examples: TagsAddedSuccessfully: value: id: 123 filename: project_proposal.pdf workspace: id: 1 name: Engineering Team summaries: - language: en summary: This document outlines Q4 initiatives... title: Q4 Project Proposal extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 25 size: 2458624 tags: - id: 1 name: Compliance auto_assigned: false - id: 2 name: Legal auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: >- T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 parser: v2.2.1 message: Added 2 tag(s) to file (duplicates ignored) summary: Tags added successfully description: Tags added successfully '400': description: Validation error '401': description: Authentication credentials were not provided '403': description: Permission denied - user cannot edit this file '404': description: File not found security: - bearerAuth: [] components: schemas: FileTaggingAddRequest: type: object description: Request serializer for adding tags to a file. properties: tags: type: array items: type: integer description: List of tag IDs to add to the file minItems: 1 required: - tags FileRetrieveResponseSerializerV3: type: object properties: id: type: integer readOnly: true filename: type: string readOnly: true description: Filename of the document workspace: allOf: - $ref: '#/components/schemas/WorkspaceInFileResponseSerializerV3' nullable: true readOnly: true description: Workspace the document belongs to summaries: type: array items: $ref: '#/components/schemas/DocumentSummaryResponse' readOnly: true description: Document summaries (all languages) title: type: string nullable: true maxLength: 255 extension: type: string description: File extension of the document status: $ref: '#/components/schemas/Status88dEnum' status_vision: $ref: '#/components/schemas/StatusVisionEnum' created_at: type: string format: date-time description: Creation date of the resource updated_at: type: string format: date-time readOnly: true total_pages: type: integer readOnly: true description: Total number of pages size: type: integer nullable: true readOnly: true description: Size of the file in bytes. tags: type: array items: $ref: '#/components/schemas/TagItem' readOnly: true description: List of tags associated with the document created_by: allOf: - $ref: '#/components/schemas/CreatedBy' nullable: true readOnly: true description: >- User who created the file. Null when the file was created by the system. upload_session_uuid: type: string format: uuid nullable: true readOnly: true description: Upload session UUID associated with this document signature: type: string nullable: true readOnly: true description: TLSH hash for duplicate detection. content: type: string nullable: true description: >- Full text content of the document. Only included when include_content=true query parameter is provided. status_detail: type: string nullable: true description: >- Detailed error information. Only present when document processing has failed. parser: type: string nullable: true description: >- Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0'). external_metadata: allOf: - $ref: '#/components/schemas/ExternalMetadata' description: External document metadata required: - created_at - created_by - extension - external_metadata - filename - id - signature - size - summaries - tags - total_pages - updated_at - upload_session_uuid - workspace WorkspaceInFileResponseSerializerV3: type: object description: Minimal workspace info for file responses. properties: id: type: integer description: Workspace ID name: type: string description: Workspace name workspace_type: type: string description: Workspace type (company, personal, or custom) required: - id - name - workspace_type DocumentSummaryResponse: type: object properties: language: allOf: - $ref: '#/components/schemas/DocumentSummaryResponseLanguageEnum' description: |- Language of the summary. * `en` - English * `fr` - French * `es` - Spanish * `it` - Italian * `ar` - Arabic * `nl` - Dutch * `sv` - Swedish * `de` - German * `ja` - Japanese * `zh` - Chinese * `ko` - Korean summary: type: string description: Summary of the document. required: - summary Status88dEnum: enum: - pending - parsing - parsing_failed - embedding - embedding_failed - embedded - fail - updating type: string description: |- * `pending` - Pending * `parsing` - Parsing * `parsing_failed` - Parsing Failed * `embedding` - Embedding * `embedding_failed` - Embedding Failed * `embedded` - Embedded * `fail` - Fail * `updating` - Updating StatusVisionEnum: enum: - pending - processing - embedded - fail - '-' type: string description: |- * `pending` - Pending * `processing` - Processing * `embedded` - Embedded * `fail` - Fail * `-` - Not available TagItem: type: object description: Serializer for tag items in file list response. properties: id: type: integer description: Tag ID name: type: string description: Tag name auto_assigned: type: boolean description: >- True if this tag was automatically assigned by the system, False if manually assigned by a user required: - auto_assigned - id - name CreatedBy: type: object description: Shallow user object for the file creator. properties: id: type: integer description: User ID first_name: type: string description: First name last_name: type: string description: Last name username: type: string description: Username required: - first_name - id - last_name - username ExternalMetadata: type: object properties: external_id: type: string description: External document ID doc_type: type: string description: External document type additional_metadata: description: Additional metadata associated with the document required: - additional_metadata - doc_type - external_id DocumentSummaryResponseLanguageEnum: enum: - en - fr - es - it - ar - nl - sv - de - ja - zh - ko type: string description: |- * `en` - English * `fr` - French * `es` - Spanish * `it` - Italian * `ar` - Arabic * `nl` - Dutch * `sv` - Swedish * `de` - German * `ja` - Japanese * `zh` - Chinese * `ko` - Korean securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````