{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/api-reference/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["api-container","api-content","endpoint","api-examples","tabs","tab","code-group"]},"redocly_category":"API Reference","searchWeight":120,"type":"markdown"},"seo":{"title":"Import words into a vocabulary list","description":"Complete API reference and documentation for Freddy AI-powered backend system by Aitronos","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"import-words-into-a-vocabulary-list","__idx":0},"children":["Import words into a vocabulary list"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add and update words from an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".xlsx"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".csv"]}," file of up to 5 MB and 10,000 rows. A word already in the list (same written form and language, ignoring case) is updated; nothing is ever deleted. Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dry_run"]}," to check a file without writing. Needs edit rights on the list. A file that would take the list past its limit writes nothing."]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"ApiContent","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"POST","path":"https://api.aitronos.com/v1/vocabulary/lists/{list_id}/import"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"path-parameters","__idx":1},"children":["Path Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["list_id"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#ef4444 !important","fontWeight":"600 !important","fontStyle":"normal !important"}},"children":["required"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list to import into."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-body","__idx":2},"children":["Request Body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]}]}," file ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#ef4444 !important","fontWeight":"600 !important","fontStyle":"normal !important"}},"children":["required"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".xlsx"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".csv"]}," file. The first row names the columns: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["written"]}," (required), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sounds_like"]}," (several separated by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[";"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["weight"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enabled"]},". A column left out keeps the stored value. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".csv"]}," may use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[","]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[";"]}," and may start with a byte-order mark."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dry_run"]}]}," boolean ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}," · Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the file without writing."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":3},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dry_run"]}]}," boolean"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["True when nothing was written."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created"]}]}," integer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Words added to the list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated"]}]}," integer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Words of the list that were changed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unchanged"]}]}," integer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Words already in the list as given."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}]}," integer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rows skipped because of an error."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}]}," array"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The first 500 rows that are not unchanged: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["row"]}," (counting the header as row 1), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["written"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," — one of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["written_missing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["written_too_long"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language_invalid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind_invalid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["weight_invalid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["replace_needs_sounds_like"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["too_many_sounds_like"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sounds_like_too_long"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["duplicate_in_file"]},"."]}]},{"$$mdtype":"Tag","name":"ApiExamples","attributes":{},"children":[{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"dropdown"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl -X POST \"https://api.aitronos.com/v1/vocabulary/lists/voclist_8f2a61c4e0b94d7a/import\" \\\n  -H \"X-API-Key: $FREDDY_API_KEY\" \\\n  -F \"file=@words.csv\" \\\n  -F \"dry_run=true\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"import os\nimport requests\n\napi_key = os.environ[\"FREDDY_API_KEY\"]\n\nwith open(\"words.csv\", \"rb\") as file:\n    response = requests.post(\n        \"https://api.aitronos.com/v1/vocabulary/lists/voclist_8f2a61c4e0b94d7a/import\",\n        headers={\"X-API-Key\": api_key},\n        files={\"file\": (\"words.csv\", file, \"text/csv\")},\n        data={\"dry_run\": \"true\"},\n    )\n\nprint(response.json())\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const apiKey = process.env.FREDDY_API_KEY;\n\nconst form = new FormData();\nform.append('file', fileInput.files[0]);\nform.append('dry_run', 'true');\n\nconst response = await fetch('https://api.aitronos.com/v1/vocabulary/lists/voclist_8f2a61c4e0b94d7a/import', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': apiKey\n  },\n  body: form\n});\n\nconst data = await response.json();\nconsole.log(data);\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"200 OK","header":{"title":"200 OK","controls":{"copy":{}}},"source":"{\n  \"dry_run\": true,\n  \"created\": 41,\n  \"updated\": 3,\n  \"unchanged\": 112,\n  \"errors\": 1,\n  \"rows\": [\n    {\n      \"row\": 7,\n      \"status\": \"updated\",\n      \"written\": \"Kubernetes\",\n      \"error\": null\n    },\n    {\n      \"row\": 12,\n      \"status\": \"error\",\n      \"written\": null,\n      \"error\": \"written_missing\"\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Errors","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"401 Unauthorized","header":{"title":"401 Unauthorized","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"AUTHENTICATION_REQUIRED\",\n    \"message\": \"Authentication required. Please provide a valid API key.\",\n    \"system_message\": \"Missing or invalid authorization header\",\n    \"type\": \"authentication_error\",\n    \"status\": 401,\n    \"details\": {},\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-26T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"403 Forbidden","header":{"title":"403 Forbidden","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INSUFFICIENT_PERMISSIONS\",\n    \"message\": \"You do not have permission to perform this action.\",\n    \"system_message\": \"Caller lacks the rights this operation needs.\",\n    \"type\": \"authorization_error\",\n    \"status\": 403,\n    \"details\": {},\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-26T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"404 Not Found","header":{"title":"404 Not Found","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VOCABULARY_LIST_NOT_FOUND\",\n    \"message\": \"The vocabulary list was not found.\",\n    \"system_message\": \"Vocabulary list not found.\",\n    \"type\": \"client_error\",\n    \"status\": 404,\n    \"details\": {},\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-26T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"409 Conflict","header":{"title":"409 Conflict","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"DICTIONARY_LIMIT_REACHED\",\n    \"message\": \"The vocabulary limit of 5000 entries is reached.\",\n    \"system_message\": \"Vocabulary list entry limit reached.\",\n    \"type\": \"client_error\",\n    \"status\": 409,\n    \"details\": {\n      \"limit\": 5000,\n      \"current_count\": 4990\n    },\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-26T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"422 Unprocessable Entity","header":{"title":"422 Unprocessable Entity","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VOCABULARY_IMPORT_INVALID\",\n    \"message\": \"The vocabulary file cannot be imported.\",\n    \"system_message\": \"Vocabulary import refused.\",\n    \"type\": \"validation_error\",\n    \"status\": 422,\n    \"details\": {\n      \"reason\": \"missing_written_column\"\n    },\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-26T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":4},"children":["Related Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/vocabulary/export-a-vocabulary-list"},"children":["Export a vocabulary list"]}," — Download a list in the same format."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/vocabulary/_index"},"children":["Vocabulary API"]}," — Overview of lists, entries and settings."]}]}]},"headings":[{"value":"Import words into a vocabulary list","id":"import-words-into-a-vocabulary-list","depth":1},{"value":"Path Parameters","id":"path-parameters","depth":4},{"value":"Request Body","id":"request-body","depth":4},{"value":"Returns","id":"returns","depth":2},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Import words into a vocabulary list","keywords":["import words into a vocabulary list","post","import","vocabulary","list","xlsx","csv"],"seo":{"title":"Import words into a vocabulary list"}},"lastModified":"2026-10-26T18:31:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/vocabulary/import-words-into-a-vocabulary-list","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}