{"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":"Create 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":"create-a-vocabulary-list","__idx":0},"children":["Create a vocabulary list"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a custom vocabulary list owned by the caller, optionally in a team space the caller is an active member of. An organization holds at most 500 lists. To share the list, create an access grant on it."]},{"$$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"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-body","__idx":1},"children":["Request Body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]}," 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 name, 1 to 200 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An optional description, up to 1000 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["team_space_id"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Place the list in a team space the caller is an active member of."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":2},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The new vocabulary list:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list ID."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organization"]}," for the one list every organization has; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]}," otherwise."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list name."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]}," string or null"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An optional description."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["team_space_id"]}]}," string or null"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The team space the list belongs to, if any."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["owner_user_id"]}]}," string or null"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The person who owns the list; null for the organization list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enabled"]}]}," boolean"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whether the list's words are used in transcripts."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entry_count"]}]}," integer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Live entries in the list the caller can read."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reached_through"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How the list reached the caller: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["owner"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["person"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["department"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["team"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["team_space"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organization"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["admin"]}," (only through administration rights)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["can_edit"]}]}," boolean"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whether the caller may change the list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["can_share"]}]}," boolean"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whether the caller may share the list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["can_delete"]}]}," boolean"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whether the caller may delete the list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the list was created."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated_at"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the list last changed."]}]},{"$$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\" \\\n  -H \"X-API-Key: $FREDDY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Product names\", \"description\": \"Names of our products and features.\"}'\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\nresponse = requests.post(\n    \"https://api.aitronos.com/v1/vocabulary/lists\",\n    headers={\"X-API-Key\": api_key},\n    json={\"name\": \"Product names\", \"description\": \"Names of our products and features.\"},\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 response = await fetch('https://api.aitronos.com/v1/vocabulary/lists', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': apiKey,\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\"name\": \"Product names\", \"description\": \"Names of our products and features.\"})\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":"201 Created","header":{"title":"201 Created","controls":{"copy":{}}},"source":"{\n  \"id\": \"voclist_8f2a61c4e0b94d7a\",\n  \"kind\": \"custom\",\n  \"name\": \"Product names\",\n  \"description\": \"Names of our products and features.\",\n  \"team_space_id\": null,\n  \"owner_user_id\": \"usr_3c91d0a2b7e4\",\n  \"enabled\": true,\n  \"entry_count\": 0,\n  \"reached_through\": \"owner\",\n  \"can_edit\": true,\n  \"can_share\": true,\n  \"can_delete\": true,\n  \"created_at\": \"2026-10-24T09:30:00Z\",\n  \"updated_at\": \"2026-10-24T09:30:00Z\"\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-24T09: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\": \"VOCABULARY_TEAM_SPACE_FORBIDDEN\",\n    \"message\": \"You are not a member of this team space.\",\n    \"system_message\": \"Caller is not a member of the team space.\",\n    \"type\": \"authorization_error\",\n    \"status\": 403,\n    \"details\": {\n      \"team_space_id\": \"tsp_4e8a1c\"\n    },\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-24T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":3},"children":["Related Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/access-control/create-grant"},"children":["Create an access grant"]}," — Share a vocabulary list with people, teams or the whole organization."]}]}]},"headings":[{"value":"Create a vocabulary list","id":"create-a-vocabulary-list","depth":1},{"value":"Request Body","id":"request-body","depth":4},{"value":"Returns","id":"returns","depth":2},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Create a vocabulary list","keywords":["create a vocabulary list","post","create","a","vocabulary","list"],"seo":{"title":"Create a vocabulary list"}},"lastModified":"2026-10-25T12:39:00.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/vocabulary/create-a-vocabulary-list","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}