> ## Documentation Index > Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # List File Categories > List the file category vocabulary — company-wide, or scoped to one entity type's admin-configured list via the optional `entityType` parameter. Category values are stored as free text on a placement, and **writes are never validated against the configured lists**: setting a `category` via **Update File** or **Update File Placement** accepts any non-blank string up to 255 characters. This endpoint is the vocabulary to draw from so the set stays consistent instead of fragmenting. Company admins manage the configured lists in **Company Settings → File Categories**. **With `entityType`** — that entity type's configured categories in their configured order, followed by the labels in use on its live placements that no configured category covers. `entityTypeCategories` flags every entry with `configured`; `categories` repeats the same names in the same order without the flags. Categories are configured per entity type, so a Policy list and an Event list are independent. An unconfigured in-use value comes from an import, an API write, or a category an admin has removed — it stays listed so it remains visible and filterable. **Without `entityType`** — the distinct category values in use across **every** owner's live file placements, under `categories` alone: - The set is **company-wide**, not scoped to any owner: a category set on a company-level file and one set on a quote's file both appear here. - Only **live** placements contribute — a category that survives only on a soft-deleted placement (or a soft-deleted file) is excluded. A category that is still in use on any live placement remains. - Values are returned once each, sorted case-insensitively. - The configured lists are not consulted, so a configured category that no file uses yet does not appear. - A company with no categorized live placements returns an empty array. **Required permission:** `company.file:read` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/files/categories openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://go.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/companies/{companyId}/files/categories: get: tags: - Company Files summary: List File Categories description: > List the file category vocabulary — company-wide, or scoped to one entity type's admin-configured list via the optional `entityType` parameter. Category values are stored as free text on a placement, and **writes are never validated against the configured lists**: setting a `category` via **Update File** or **Update File Placement** accepts any non-blank string up to 255 characters. This endpoint is the vocabulary to draw from so the set stays consistent instead of fragmenting. Company admins manage the configured lists in **Company Settings → File Categories**. **With `entityType`** — that entity type's configured categories in their configured order, followed by the labels in use on its live placements that no configured category covers. `entityTypeCategories` flags every entry with `configured`; `categories` repeats the same names in the same order without the flags. Categories are configured per entity type, so a Policy list and an Event list are independent. An unconfigured in-use value comes from an import, an API write, or a category an admin has removed — it stays listed so it remains visible and filterable. **Without `entityType`** — the distinct category values in use across **every** owner's live file placements, under `categories` alone: - The set is **company-wide**, not scoped to any owner: a category set on a company-level file and one set on a quote's file both appear here. - Only **live** placements contribute — a category that survives only on a soft-deleted placement (or a soft-deleted file) is excluded. A category that is still in use on any live placement remains. - Values are returned once each, sorted case-insensitively. - The configured lists are not consulted, so a configured category that no file uses yet does not appear. - A company with no categorized live placements returns an empty array. **Required permission:** `company.file:read` operationId: listCompanyFileCategories parameters: - $ref: '#/components/parameters/companyId' - name: entityType in: query required: false description: >- Scope the read to one owner entity type's configured list. The lowercase kebab-case owner slug — PascalCase (e.g. `Quote`) is rejected with a `400`. Omit for the company-wide in-use listing. schema: type: string enum: - company - event - exposure - quote - policy - submission - person - organization responses: '200': description: The file category vocabulary content: application/json: schema: type: object properties: categories: type: array description: >- Without `entityType`: the distinct non-null category values across the company's live file placements, each appearing once, sorted case-insensitively. With `entityType`: that type's vocabulary as bare names — the configured categories in configured order, then the unconfigured in-use values. items: type: string entityType: type: string description: >- The requested owner entity type, echoed as its wire slug. Present only when the request carried `entityType`. enum: - company - event - exposure - quote - policy - submission - person - organization entityTypeCategories: type: array description: >- The scoped vocabulary with every entry flagged. Present only when the request carried `entityType`; lists the same names in the same order as `categories`. items: type: object properties: name: type: string description: >- The category label, exactly as it lands on a placement configured: type: boolean description: >- `true` when a configured category for this entity type defines the label; `false` when the label is only in use on placements (an import, an API write, or a category an admin has removed) required: - name - configured required: - categories examples: success: summary: Categories in use (company-wide) value: categories: - Applications - Endorsements - Loss Runs scoped: summary: One entity type's configured vocabulary value: categories: - Applications - Loss Runs - Legacy Import entityType: quote entityTypeCategories: - name: Applications configured: true - name: Loss Runs configured: true - name: Legacy Import configured: false empty: summary: No categorized files yet value: categories: [] '400': description: Bad Request — invalid entity type content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidEntityType: summary: PascalCase or unknown owner slug value: error: code: BadRequest message: >- Invalid entity type. Must be a configured entity (lowercase kebab-case, e.g. 'exposure') or 'company'. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' userMessages: type: array description: >- Clean, verbatim-displayable messages — one entry per failure, free of error-code tags, field paths, and internal noise. Suitable for showing to end users as-is. items: type: string example: - Exposures of type 'company' require an address details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId message: type: string description: Description of the field error example: Required field is missing responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: AuthenticationError message: API key authentication required userMessages: - API key authentication required invalidApiKey: summary: >- Invalid API key (e.g. unknown key, or a Bearer token used instead of an API key) value: error: code: AuthenticationError message: Invalid API key userMessages: - Invalid API key Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: AuthorizationError message: User is not authorized to perform the requested action userMessages: - User is not authorized to perform the requested action companyMismatch: summary: A valid API key naming another company in the URL value: error: code: AuthorizationError message: API key is not scoped to the requested company userMessages: - API key is not scoped to the requested company InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: UncaughtActionError message: Uncaught error occurred in userMessages: - An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Send your raw API key as the `Authorization` header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key` header; those are not accepted. ````