{"openapi":"3.0.0","info":{"title":"Afineo Webservices API — import","description":"Module `import` of the Afineo API v3 (4 endpoints).\n\nImport asset data into the platform. Supports auto-mapped imports and JSON/JSONL formats, in both repository and project contexts. Data can be sent inline via the data parameter or as a file upload.\n\nFull specification: https://api.afineo.io/openapi.json","version":"3.0.0","contact":{"name":"Afineo Solutions","url":"https://www.afineo.com"},"x-logo":{"url":"./logo.png","altText":"Afineo - Powerful Data, Powerful People"}},"servers":[{"url":"https://{instance}.afineo.io","description":"Afineo instance","variables":{"instance":{"description":"Your Afineo instance name","default":"client"}}}],"tags":[{"name":"import","description":"Import asset data into the platform. Supports auto-mapped imports and JSON/JSONL formats, in both repository and project contexts. Data can be sent inline via the data parameter or as a file upload."}],"paths":{"/api/v3/import/auto/node/":{"post":{"tags":["import"],"summary":"Auto-mapped import in node (project context)","description":"## Purpose\n\nImports data from CSV or Excel files into a specific node/project context using automatic attribute mapping based on column headers.\n\n## Content-Type\n\nThis endpoint requires `multipart/form-data` content type.\n\n## Supported File Formats\n\nFile type is automatically detected from file extension:\n- **CSV**: Text-based comma/semicolon separated values\n- **XLSX**: Excel 2007+ format (Office Open XML)\n\n## Example with curl\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/auto/node/\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -F \"class_id=4\" \\\n  -F \"parent_id=12345\" \\\n  -F \"file=@/path/to/data.csv\" \\\n  -F \"separator=;\" \\\n  -F \"mode=create_in_context\"\n```\n\n## Auto-Mapping Rules\n\nThe system automatically maps columns to attributes using these rules:\n1. **By uname**: Column header matches attribute uname exactly\n2. **By label**: Column header matches attribute label exactly\n\n## Header Conventions\n\n| Suffix | Meaning | Example |\n|--------|---------|---------|\n| `*` | Key column (used to identify existing assets) | `reference*` |\n| `!` | Associated data (linked entity) | `category!` |\n| `[suffix]` | Cross-reference data | `price[EUR]` |\n\n## Update Modes (Node/Project)\n\n- `create_in_context`: Create assets in the specified node context (default)\n- `update_in_context`: Update existing assets in the context\n- `classify_only`: Only classify assets (no data modification)\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Import response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Import success status"},"mapping":{"type":"object","properties":{"resolved":{"type":"array","items":{"type":"object","properties":{"column":{"type":"integer","example":1,"description":"Column index (1-based)"},"header":{"type":"string","example":"reference*","description":"Original column header from file"},"attribute_id":{"type":"integer","nullable":true,"example":145,"description":"Matched attribute ID. Null if mapped to a system field."},"system_field":{"type":"string","nullable":true,"example":"[ID_FICHE]","description":"System field identifier (e.g., [ID_FICHE], [ID_NODE], [ID_TYPE], [STATUT]). Only present for system field mappings."},"is_key":{"type":"boolean","example":true,"description":"Whether this column is marked as a key column (header ends with *)"}}},"description":"Columns successfully mapped to attributes or system fields"},"unresolved":{"type":"array","items":{"type":"object","properties":{"column":{"type":"integer","example":3,"description":"Column index (1-based)"},"header":{"type":"string","example":"unknown_column","description":"Column header that could not be matched to any attribute"}}},"description":"Columns that could not be mapped (no matching uname or label found in the class)"}},"description":"Mapping information"},"stats":{"type":"object","properties":{"total_rows":{"type":"integer","example":1500,"description":"Total number of data rows processed"},"created":{"type":"integer","example":1200,"description":"Number of assets created"},"updated":{"type":"integer","example":300,"description":"Number of assets updated"},"excluded":{"type":"integer","example":0,"description":"Number of rows excluded (no key value)"},"errors":{"type":"integer","example":0,"description":"Number of rows with errors"}},"required":["total_rows","created","updated","excluded","errors"],"description":"Import statistics"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","description":"Row number"},"message":{"type":"string","description":"Error message"}}},"description":"List of row-level errors"},"history_id":{"type":"integer","example":12345,"description":"ID of the import action in the history log. Can be used to track or reference this import operation."}},"required":["success","mapping","stats","errors"],"description":"Import result"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":2,"description":"Status code (2 = Parameters error, 3 = Import error)"},"status_message":{"type":"string","example":"Invalid file format","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.","example":4},"parent_id":{"type":"integer","description":"Parent node ID in project. Use POST /api/v3/get-asset/by-search/node to find project nodes.","example":12345},"file":{"type":"string","format":"binary","description":"The file to import. Must be sent as multipart/form-data with a filename including a valid extension (e.g. products.csv). Supported formats: CSV, XLSX. Sending the file as raw binary without a filename will result in an error.","example":"products.csv"},"mode":{"type":"string","description":"Import mode: \"create_in_context\" (create nodes in project), \"update_in_context\" (update existing nodes), \"classify_only\" (classify without modification).","enum":["create_in_context","update_in_context","classify_only"],"example":"create_in_context"},"separator":{"type":"string","description":"CSV column separator (default: \";\"). Only used for CSV files","example":";"},"header_row":{"type":"integer","description":"Row number containing column headers (default: 1)","example":1},"data_start_row":{"type":"integer","description":"Row number where data starts (default: 2)","example":2},"type_id":{"type":"integer","description":"Asset type ID for created assets. Use POST /api/v3/types/list with class_id to get available types.","example":257},"version_id":{"type":"integer","description":"Version ID for multilingual imports. Use POST /api/v3/administration/versions/list with class_id to get available versions.","example":1}},"required":["class_id","parent_id","mode"]}}}}}},"/api/v3/import/auto/repository/":{"post":{"tags":["import"],"summary":"Auto-mapped import in repository","description":"## Purpose\n\nImports data from CSV or Excel files into the repository using automatic attribute mapping based on column headers.\n\n## Content-Type\n\nThis endpoint requires `multipart/form-data` content type.\n\n## Supported File Formats\n\nFile type is automatically detected from file extension:\n- **CSV**: Text-based comma/semicolon separated values\n- **XLSX**: Excel 2007+ format (Office Open XML)\n\n## Example with curl\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/auto/repository/\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -F \"class_id=4\" \\\n  -F \"file=@/path/to/data.csv\" \\\n  -F \"separator=;\" \\\n  -F \"mode=create_or_update\"\n```\n\n## Auto-Mapping Rules\n\nThe system automatically maps columns to attributes using these rules:\n1. **By uname**: Column header matches attribute uname exactly\n2. **By label**: Column header matches attribute label exactly\n\n## Header Conventions\n\n| Suffix | Meaning | Example |\n|--------|---------|---------|\n| `*` | Key column (used to identify existing assets) | `reference*` |\n| `!` | Associated data (linked entity) | `category!` |\n| `[suffix]` | Cross-reference data | `price[EUR]` |\n\n## Update Modes (Repository)\n\n- `create_only`: Only create new assets, skip existing ones\n- `update_only`: Only update existing assets, skip new ones\n- `create_or_update`: Create new assets or update existing ones (default)\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Import response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Import success status"},"mapping":{"type":"object","properties":{"resolved":{"type":"array","items":{"type":"object","properties":{"column":{"type":"integer","example":1,"description":"Column index (1-based)"},"header":{"type":"string","example":"reference*","description":"Original column header from file"},"attribute_id":{"type":"integer","nullable":true,"example":145,"description":"Matched attribute ID. Null if mapped to a system field."},"system_field":{"type":"string","nullable":true,"example":"[ID_FICHE]","description":"System field identifier (e.g., [ID_FICHE], [ID_NODE], [ID_TYPE], [STATUT]). Only present for system field mappings."},"is_key":{"type":"boolean","example":true,"description":"Whether this column is marked as a key column (header ends with *)"}}},"description":"Columns successfully mapped to attributes or system fields"},"unresolved":{"type":"array","items":{"type":"object","properties":{"column":{"type":"integer","example":3,"description":"Column index (1-based)"},"header":{"type":"string","example":"unknown_column","description":"Column header that could not be matched to any attribute"}}},"description":"Columns that could not be mapped (no matching uname or label found in the class)"}},"description":"Mapping information"},"stats":{"type":"object","properties":{"total_rows":{"type":"integer","example":1500,"description":"Total number of data rows processed"},"created":{"type":"integer","example":1200,"description":"Number of assets created"},"updated":{"type":"integer","example":300,"description":"Number of assets updated"},"excluded":{"type":"integer","example":0,"description":"Number of rows excluded (no key value)"},"errors":{"type":"integer","example":0,"description":"Number of rows with errors"}},"required":["total_rows","created","updated","excluded","errors"],"description":"Import statistics"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","description":"Row number"},"message":{"type":"string","description":"Error message"}}},"description":"List of row-level errors"},"history_id":{"type":"integer","example":12345,"description":"ID of the import action in the history log. Can be used to track or reference this import operation."}},"required":["success","mapping","stats","errors"],"description":"Import result"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":2,"description":"Status code (2 = Parameters error, 3 = Import error)"},"status_message":{"type":"string","example":"Invalid file format","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.","example":4},"parent_id":{"type":"integer","description":"Parent asset ID in repository. Use POST /api/v3/get-asset/by-search/repository to find assets. Set to 0 for repository root.","example":0},"file":{"type":"string","format":"binary","description":"The file to import. Must be sent as multipart/form-data with a filename including a valid extension (e.g. products.csv). Supported formats: CSV, XLSX. Sending the file as raw binary without a filename will result in an error.","example":"products.csv"},"mode":{"type":"string","description":"Import mode: \"create_only\" (new assets only), \"update_only\" (existing assets only), \"create_or_update\" (both).","enum":["create_only","update_only","create_or_update"],"example":"create_or_update"},"separator":{"type":"string","description":"CSV column separator (default: \";\"). Only used for CSV files","example":";"},"header_row":{"type":"integer","description":"Row number containing column headers (default: 1)","example":1},"data_start_row":{"type":"integer","description":"Row number where data starts (default: 2)","example":2},"type_id":{"type":"integer","description":"Asset type ID for created assets. Use POST /api/v3/types/list with class_id to get available types.","example":257},"version_id":{"type":"integer","description":"Version ID for multilingual imports. Use POST /api/v3/administration/versions/list with class_id to get available versions.","example":1}},"required":["class_id","mode"]}}}}}},"/api/v3/import/json/node/":{"post":{"tags":["import"],"summary":"Import JSON/JSONL data in node (project context)","description":"## Purpose\n\nImports data from JSON or JSONL format into a specific node/project context. Supports two input modes:\n1. **Inline data**: Pass JSON data directly via the `data` parameter\n2. **File upload**: Upload a JSON/JSONL file via multipart/form-data\n\n## Content-Type\n\n- For inline data: `application/json`\n- For file upload: `multipart/form-data`\n\n## JSON Schema\n\n### Line Structure (JSONL format)\n\nEach line represents one asset to import:\n\n```jsonl\n{\"key\": {...}, \"type_id\": 257, \"fields\": [...]}\n```\n\n### Asset Identification (`key`)\n\n```jsonl\n// By direct asset_id\n{\"key\": {\"id\": 5845}, \"fields\": [...]}\n\n// By key attribute (code/uname)\n{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"fields\": [...]}\n\n// By key attribute (numeric id)\n{\"key\": {\"attr\": 231, \"value\": \"ABC123\"}, \"fields\": [...]}\n```\n\n### Attribute Resolution (`id` and `attr`)\n\nThe `attr` parameter resolves attributes in this order:\n1. **Numeric ID**: Direct attribute ID (e.g., `231`)\n2. **Uname**: Attribute uname/code (e.g., `\"designationlibelle\"`)\n3. **Label**: Attribute label (e.g., `\"Designation\"`)\n\nUse POST /api/v3/attributes/list to retrieve attribute IDs and unames.\n\n### Attribute Fields (`fields`)\n\n```jsonl\n// Simple attribute by ID\n{\"id\": 231, \"value\": \"Product A\"}\n\n// With language version\n{\"id\": 658, \"value\": \"Red leather\", \"version\": 1}\n\n// By attribute code/uname instead of ID\n{\"attr\": \"designationlabel\", \"value\": \"Text\", \"version\": 2}\n\n// Multiple values (sync required)\n{\"id\": 724, \"value\": [\"Red\", \"Black\"], \"sync\": true}\n\n// Associated data with search key\n{\"id\": 800, \"value\": [\"SKU1\", \"SKU2\"], \"keyassoc\": 231, \"sync\": true}\n```\n\n### Field Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `id` or `attr` | Yes | Attribute numeric ID, code/uname, or label |\n| `value` | Yes | Value (string, number, or array for multiples) |\n| `version` | No | Language version ID (default version if absent) |\n| `sync` | **Required if array** | `true` = replace all, `false` = append |\n| `keyassoc` | No | Key attribute ID for associated data |\n\n## Important Notes\n\n- **`type_id` is required when creating assets** (modes `create_in_context`). Without it, rows will fail with an error. It can be set globally via the `type_id` parameter or per line via the `type_id` field in each JSON object.\n\n## Examples with curl\n\n### Mode 1: Inline JSON (data parameter)\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/json/node/\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"class_id\": 4,\n    \"parent_id\": 12345,\n    \"mode\": \"create_in_context\",\n    \"type_id\": 257,\n    \"data\": [\n      {\"key\": {\"attr\": \"reference\", \"value\": \"ABC\"}, \"fields\": [{\"id\": 231, \"value\": \"Product A\"}]},\n      {\"key\": {\"attr\": \"reference\", \"value\": \"DEF\"}, \"fields\": [{\"id\": 231, \"value\": \"Product B\"}]}\n    ]\n  }'\n```\n\n### Mode 2: File upload\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/json/node/\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -F \"class_id=4\" \\\n  -F \"parent_id=12345\" \\\n  -F \"mode=create_in_context\" \\\n  -F \"file=@/path/to/data.jsonl\"\n```\n\n## Update Modes (Node/Project)\n\n- `create_in_context`: Create assets in the specified node context (default)\n- `update_in_context`: Update existing assets in the context\n- `classify_only`: Only classify assets (no data modification)\n\n## Common Errors\n\n| Error Code | Message | Cause | Solution |\n|------------|---------|-------|----------|\n| 2 | \"No data provided\" | Neither `data` nor `file` parameter | Provide exactly one of `data` or `file` |\n| 2 | \"Cannot use both data and file\" | Both parameters provided | Use only one input mode |\n| 2 | \"Parent node does not exist\" | Invalid parent_id | Use valid node ID from project |\n| 2 | \"Invalid file format\" | File is not .json or .jsonl | Use JSON or JSONL file extension |\n| 3 | \"JSON parse error on line X\" | Malformed JSON in file | Fix JSON syntax at specified line |\n| 3 | \"Not allowed operation\" | No permission on project | Check user project permissions |\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"JSON Import response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Import success status"},"stats":{"type":"object","properties":{"total_rows":{"type":"integer","example":2,"description":"Total number of data rows processed"},"created":{"type":"integer","example":1,"description":"Number of assets created"},"updated":{"type":"integer","example":1,"description":"Number of assets updated"},"excluded":{"type":"integer","example":0,"description":"Number of rows excluded (no key value)"},"errors":{"type":"integer","example":0,"description":"Number of rows with errors"}},"required":["total_rows","created","updated","excluded","errors"],"description":"Import statistics"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","example":3,"description":"Row number where error occurred"},"message":{"type":"string","example":"Invalid attribute ID: 999","description":"Error message describing the issue"}}},"example":[{"row":3,"message":"Invalid attribute ID: 999"}],"description":"List of row-level errors encountered during import"},"history_id":{"type":"integer","example":12345,"description":"ID of the import action in the history log"}},"required":["success","stats","errors"],"description":"Import result"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":2,"description":"Status code (2 = Parameters error, 3 = Import error)"},"status_message":{"type":"string","example":"No data provided. Use either \"data\" parameter (JSON body) or \"file\" parameter (multipart upload)","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.","example":4},"parent_id":{"type":"integer","description":"Parent node ID in project. Use POST /api/v3/get-asset/by-search/node to find project nodes.","example":12345},"mode":{"type":"string","description":"Import mode: \"create_in_context\" (create nodes in project), \"update_in_context\" (update existing nodes), \"classify_only\" (classify without modification).","enum":["create_in_context","update_in_context","classify_only"],"example":"create_in_context"},"data":{"type":"array","description":"**MUTUALLY EXCLUSIVE with `file`** - Array of JSON objects to import (inline mode). Each object must contain `key` (asset identification), optionally `type_id`, and `fields` array. Exactly one of `data` or `file` must be provided.","example":"[{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"type_id\": 257, \"fields\": [{\"id\": 231, \"value\": \"Product A\"}]}]","items":{"type":"string"}},"file":{"type":"string","format":"binary","description":"**MUTUALLY EXCLUSIVE with `data`** - JSON (.json) or JSONL (.jsonl) file to import. Must be sent as multipart/form-data with a filename including a valid extension (e.g. products.jsonl). Sending the file as raw binary without a filename will result in an error. Exactly one of `data` or `file` must be provided.","example":"products.jsonl"},"type_id":{"type":"integer","description":"Asset type ID for created assets. **Required when creating assets** (without it, creation will fail). Can be overridden per line with type_id field. Use POST /api/v3/types/list with class_id to get available types.","example":257},"version_id":{"type":"integer","description":"Default version ID for multilingual imports (can be overridden per field with version). Use POST /api/v3/administration/versions/list with class_id to get available versions.","example":1}},"required":["class_id","parent_id","mode"]}}}}}},"/api/v3/import/json/repository/":{"post":{"tags":["import"],"summary":"Import JSON/JSONL data in repository","description":"## Purpose\n\nImports data from JSON or JSONL format into the repository. Supports two input modes:\n1. **Inline data**: Pass JSON data directly via the `data` parameter\n2. **File upload**: Upload a JSON/JSONL file via multipart/form-data\n\n## Content-Type\n\n- For inline data: `application/json`\n- For file upload: `multipart/form-data`\n\n## JSON Schema\n\n### Line Structure (JSONL format)\n\nEach line represents one asset to import:\n\n```jsonl\n{\"key\": {...}, \"type_id\": 257, \"fields\": [...]}\n```\n\n### Asset Identification (`key`)\n\n```jsonl\n// By direct asset_id\n{\"key\": {\"id\": 5845}, \"fields\": [...]}\n\n// By key attribute (code/uname)\n{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"fields\": [...]}\n\n// By key attribute (numeric id)\n{\"key\": {\"attr\": 231, \"value\": \"ABC123\"}, \"fields\": [...]}\n```\n\n### Attribute Resolution (`id` and `attr`)\n\nThe `attr` parameter resolves attributes in this order:\n1. **Numeric ID**: Direct attribute ID (e.g., `231`)\n2. **Uname**: Attribute uname/code (e.g., `\"designationlibelle\"`)\n3. **Label**: Attribute label (e.g., `\"Designation\"`)\n\nUse POST /api/v3/attributes/list to retrieve attribute IDs and unames.\n\n### Attribute Fields (`fields`)\n\n```jsonl\n// Simple attribute by ID\n{\"id\": 231, \"value\": \"Product A\"}\n\n// With language version\n{\"id\": 658, \"value\": \"Red leather\", \"version\": 1}\n\n// By attribute code/uname instead of ID\n{\"attr\": \"designationlabel\", \"value\": \"Text\", \"version\": 2}\n\n// Multiple values (sync required)\n{\"id\": 724, \"value\": [\"Red\", \"Black\"], \"sync\": true}\n\n// Associated data with search key\n{\"id\": 800, \"value\": [\"SKU1\", \"SKU2\"], \"keyassoc\": 231, \"sync\": true}\n```\n\n### Complete JSONL Example\n\n```jsonl\n{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"type_id\": 257, \"fields\": [{\"id\": 231, \"value\": \"3-seater sofa\"}, {\"id\": 658, \"value\": \"Red leather\", \"version\": 1}, {\"id\": 658, \"value\": \"Cuir rouge\", \"version\": 2}, {\"id\": 724, \"value\": [\"Red\", \"Black\"], \"sync\": true}]}\n{\"key\": {\"attr\": \"reference\", \"value\": \"DEF456\"}, \"type_id\": 257, \"fields\": [{\"id\": 231, \"value\": \"Coffee table\"}, {\"id\": 800, \"value\": [\"ABC123\"], \"keyassoc\": 231, \"sync\": false}]}\n```\n\n### Field Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `id` or `attr` | Yes | Attribute numeric ID, code/uname, or label |\n| `value` | Yes | Value (string, number, or array for multiples) |\n| `version` | No | Language version ID (default version if absent) |\n| `sync` | **Required if array** | `true` = replace all, `false` = append |\n| `keyassoc` | No | Key attribute ID for associated data |\n\n## Important Notes\n\n- **`type_id` is required when creating assets** (modes `create_only` and `create_or_update`). Without it, rows will fail with an error. It can be set globally via the `type_id` parameter or per line via the `type_id` field in each JSON object.\n\n## Examples with curl\n\n### Mode 1: Inline JSON (data parameter)\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/json/repository/\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"class_id\": 4,\n    \"mode\": \"create_or_update\",\n    \"type_id\": 257,\n    \"data\": [\n      {\"key\": {\"attr\": \"reference\", \"value\": \"ABC\"}, \"fields\": [{\"id\": 231, \"value\": \"Product A\"}]},\n      {\"key\": {\"attr\": \"reference\", \"value\": \"DEF\"}, \"fields\": [{\"id\": 231, \"value\": \"Product B\"}]}\n    ]\n  }'\n```\n\n### Mode 2: File upload\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/json/repository/\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -F \"class_id=4\" \\\n  -F \"mode=create_or_update\" \\\n  -F \"file=@/path/to/data.jsonl\"\n```\n\n## Update Modes (Repository)\n\n- `create_only`: Only create new assets, skip existing ones\n- `update_only`: Only update existing assets, skip new ones\n- `create_or_update`: Create new assets or update existing ones (default)\n\n## Common Errors\n\n| Error Code | Message | Cause | Solution |\n|------------|---------|-------|----------|\n| 2 | \"No data provided\" | Neither `data` nor `file` parameter | Provide exactly one of `data` or `file` |\n| 2 | \"Cannot use both data and file\" | Both parameters provided | Use only one input mode |\n| 2 | \"Invalid file format\" | File is not .json or .jsonl | Use JSON or JSONL file extension |\n| 2 | \"Parameter data must be an array\" | `data` is not a JSON array | Ensure `data` is an array of objects |\n| 3 | \"JSON parse error on line X\" | Malformed JSON in file | Fix JSON syntax at specified line |\n| 3 | \"Import error\" | Processing failed | Check attribute IDs and data format |\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"JSON Import response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Import success status"},"stats":{"type":"object","properties":{"total_rows":{"type":"integer","example":2,"description":"Total number of data rows processed"},"created":{"type":"integer","example":1,"description":"Number of assets created"},"updated":{"type":"integer","example":1,"description":"Number of assets updated"},"excluded":{"type":"integer","example":0,"description":"Number of rows excluded (no key value)"},"errors":{"type":"integer","example":0,"description":"Number of rows with errors"}},"required":["total_rows","created","updated","excluded","errors"],"description":"Import statistics"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","example":3,"description":"Row number where error occurred"},"message":{"type":"string","example":"Invalid attribute ID: 999","description":"Error message describing the issue"}}},"example":[{"row":3,"message":"Invalid attribute ID: 999"}],"description":"List of row-level errors encountered during import"},"history_id":{"type":"integer","example":12345,"description":"ID of the import action in the history log"}},"required":["success","stats","errors"],"description":"Import result"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":2,"description":"Status code (2 = Parameters error, 3 = Import error)"},"status_message":{"type":"string","example":"No data provided. Use either \"data\" parameter (JSON body) or \"file\" parameter (multipart upload)","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.","example":4},"parent_id":{"type":"integer","description":"Parent asset ID in repository. Use POST /api/v3/get-asset/by-search/repository to find assets. Set to 0 for repository root (default).","example":0},"mode":{"type":"string","description":"Import mode: \"create_only\" (new assets only), \"update_only\" (existing assets only), \"create_or_update\" (both).","enum":["create_only","update_only","create_or_update"],"example":"create_or_update"},"data":{"type":"array","description":"**MUTUALLY EXCLUSIVE with `file`** - Array of JSON objects to import (inline mode). Each object must contain `key` (asset identification), optionally `type_id`, and `fields` array. Exactly one of `data` or `file` must be provided.","example":"[{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"type_id\": 257, \"fields\": [{\"id\": 231, \"value\": \"Product A\"}]}]","items":{"type":"string"}},"file":{"type":"string","format":"binary","description":"**MUTUALLY EXCLUSIVE with `data`** - JSON (.json) or JSONL (.jsonl) file to import. Must be sent as multipart/form-data with a filename including a valid extension (e.g. products.jsonl). Sending the file as raw binary without a filename will result in an error. Exactly one of `data` or `file` must be provided.","example":"products.jsonl"},"type_id":{"type":"integer","description":"Asset type ID for created assets. **Required when creating assets** (without it, creation will fail). Can be overridden per line with type_id field. Use POST /api/v3/types/list with class_id to get available types.","example":257},"version_id":{"type":"integer","description":"Default version ID for multilingual imports (can be overridden per field with version). Use POST /api/v3/administration/versions/list with class_id to get available versions.","example":1}},"required":["class_id","mode"]}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token generated with /api/v3/token/get/"}}}}