> ## 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.

# Create a company

> This endpoint allows authorized users to create a new company.

Only SysAdmin and Account Manager roles can create companies.



## OpenAPI

````yaml /api-reference/openapi-v3-instance.yaml post /api/v3/instance/companies
openapi: 3.1.0
info:
  title: LightOn API
  version: 3.15.0 (v3-instance)
  description: >-
    LightOn gives you an API to search, parse, and ingest documents at scale.
    Build knowledge-retrieval pipelines without managing vector databases or OCR
    models.
servers:
  - url: https://paradigm.lighton.ai
security: []
tags:
  - name: Models
    description: Operations about AI models
  - 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
paths:
  /api/v3/instance/companies:
    post:
      tags:
        - Companies
      summary: Create a company
      description: |-
        This endpoint allows authorized users to create a new company.

        Only SysAdmin and Account Manager roles can create companies.
      operationId: api_v3_instance_companies_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompanyRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateCompanyRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateCompanyRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyCreateResponse'
          description: Company created successfully
        '400':
          description: Domain rule violation (name forbidden by naming policy)
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIV3ErrorResponse'
              examples:
                Forbidden:
                  value:
                    id: null
                    code: 403
                    error: insufficient_permissions
                    detail: You do not have permission to perform this action.
                    doc_url: >-
                      https://developers.lighton.ai/errors#insufficient_permissions
          description: Insufficient permissions
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIV3ErrorResponse'
              examples:
                Conflict:
                  value:
                    id: null
                    code: 409
                    error: conflict
                    detail: A resource with this name already exists.
                    doc_url: https://developers.lighton.ai/errors#conflict
          description: A resource with this name already exists
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIV3ValidationErrorResponse'
              examples:
                ValidationError:
                  value:
                    id: null
                    code: 422
                    error: validation_error
                    detail: One or more fields failed validation.
                    doc_url: https://developers.lighton.ai/errors#validation_error
                    fields:
                      <field_name>:
                        - error: required
                          detail: This field is required.
                  summary: Validation Error
          description: Request body is valid JSON but one or more fields failed validation
        '503':
          description: >-
            API is under maintenance. Check `GET /api/v3/system/status` for
            active periods and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMaintenance503'
      security:
        - bearerAuth: []
        - {}
components:
  schemas:
    CreateCompanyRequest:
      type: object
      properties:
        name:
          type: string
          description: >-
            Company name (max 32 characters, alphanumeric +
            spaces/hyphens/underscores)
          pattern: ^[a-zA-Z0-9 \-_]+$
          maxLength: 32
        dpo_email:
          type:
            - string
            - 'null'
          format: email
          description: DPO contact email
        max_users:
          type:
            - integer
            - 'null'
          description: Maximum allowed active users for this company
        allow_company_admins_to_manage_sso:
          type: boolean
          default: false
          description: Whether company admins can manage SSO configuration
        auto_provision_external_users:
          type: boolean
          default: false
          description: >-
            Automatically create user accounts when users log in via external
            auth (SSO/LDAP) for the first time.
        storage_limit_company_ws:
          type:
            - integer
            - 'null'
          description: Company workspace storage limit in MB
        storage_limit_personal_ws:
          type:
            - integer
            - 'null'
          description: Personal workspace storage limit in MB
        storage_limit_custom_ws:
          type:
            - integer
            - 'null'
          description: Custom workspace storage limit in MB
        kg_tags_enabled:
          type: boolean
          default: true
          description: >-
            Enable automatic document tagging using Knowledge Graph (requires
            global setting also enabled)
        kg_summaries_enabled:
          type: boolean
          default: true
          description: >-
            Enable automatic document summarization using Knowledge Graph
            (requires global setting also enabled)
        kg_queries_enabled:
          type: boolean
          default: true
          description: >-
            Enable automatic query suggestion generation using Knowledge Graph
            (requires global setting also enabled)
      required:
        - name
    CompanyCreateResponse:
      type: object
      description: Serializer for company creation response
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          description: The name of the company registered in the instance.
          maxLength: 255
        dpo_email:
          type:
            - string
            - 'null'
          format: email
          description: Contact email displayed in user profiles for data privacy inquiries.
          maxLength: 254
        max_users:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          description: Maximum allowed active users for this company license.
        allow_company_admins_to_manage_sso:
          type: boolean
          description: >-
            If the company admins of this company can create & manage their SSO
            configuration.
        auto_provision_external_users:
          type: boolean
          description: >-
            Automatically create user accounts when users log in via external
            auth (SSO/LDAP) for the first time.
        storage_limit_company_ws:
          type:
            - integer
            - 'null'
          maximum: 2147483647
          minimum: -2147483648
          description: >-
            Total storage ceiling for all workspace uploads combined (personal +
            all shared workspaces), in MB. Leave blank to use the default value.
            Use 0 to disable uploads.
        storage_limit_personal_ws:
          type:
            - integer
            - 'null'
          maximum: 2147483647
          minimum: -2147483648
          description: >-
            Limit for all combined personal workspaces in this company, in MB.
            Leave blank to use the default value. Use 0 to disable uploads.
        storage_limit_custom_ws:
          type:
            - integer
            - 'null'
          maximum: 2147483647
          minimum: -2147483648
          description: >-
            Limit for all combined shared workspaces in this company (including
            the company workspace), in MB. Leave blank to use the default value.
            Use 0 to disable uploads.
        created_at:
          type: string
          format: date-time
          readOnly: true
        login_method:
          allOf:
            - $ref: '#/components/schemas/LoginMethodEnum'
          description: |-
            Authentication method(s) allowed for users in this company.

            * `password` - Password
            * `sso` - Single Sign On
            * `ldap` - LDAP
        kg_tags_enabled:
          type: boolean
          description: >-
            Enable automatic document tagging using Knowledge Graph. Disabling
            this prevents token consumption for LLM-based tagging. Global
            setting must also be enabled.
        kg_summaries_enabled:
          type: boolean
          description: >-
            Enable automatic document summarization using Knowledge Graph.
            Disabling this prevents token consumption for LLM-based summaries.
            Global setting must also be enabled.
        kg_queries_enabled:
          type: boolean
          description: >-
            Enable automatic query suggestion generation using Knowledge Graph.
            Disabling this prevents token consumption for LLM-based query
            suggestions. Global setting must also be enabled.
        tier:
          allOf:
            - $ref: '#/components/schemas/TierEnum'
          description: >-
            Commercial tier for this company. Drives entitlements and billing
            posture.


            * `free` - Free

            * `pay-as-you-go` - Pay-as-you-go

            * `business` - Business
      required:
        - allow_company_admins_to_manage_sso
        - created_at
        - id
        - name
    APIV3ErrorResponse:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
          description: >-
            Job/resource id when one already exists (useful for async error
            diagnosis); null otherwise.
        code:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Error code used by the UI as a translation key
        detail:
          type: string
          description: Human-readable error message for developers
        doc_url:
          type: string
          description: Link to the error-code documentation page
      required:
        - code
        - detail
        - doc_url
        - error
        - id
    APIV3ValidationErrorResponse:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
          description: >-
            Job/resource id when one already exists (useful for async error
            diagnosis); null otherwise.
        code:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Error code used by the UI as a translation key
        detail:
          type: string
          description: Human-readable error message for developers
        doc_url:
          type: string
          description: Link to the error-code documentation page
        fields:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/APIV3FieldError'
          description: Field-level validation errors keyed by field name
      required:
        - code
        - detail
        - doc_url
        - error
        - id
    ServiceMaintenance503:
      type: object
      description: >-
        Returned by the maintenance middleware when the requested endpoint is
        blocked.
      required:
        - detail
        - error
        - mode
      properties:
        detail:
          type: string
          example: System is under maintenance.
        error:
          type: string
          example: service_maintenance
        mode:
          type: string
          enum:
            - full_shutdown
            - warning_banner
          description: >-
            `full_shutdown` blocks all traffic; `warning_banner` also blocks and
            shows a dismissible toast.
        reason:
          type: string
          description: Operator-supplied maintenance reason, if any.
        started_at:
          type: string
          format: date-time
        endpoint_category_names:
          type: array
          items:
            type: string
          description: >-
            Non-empty only for category-scoped periods. Empty means all
            endpoints are affected.
    LoginMethodEnum:
      enum:
        - password
        - sso
        - ldap
      type: string
      description: |-
        * `password` - Password
        * `sso` - Single Sign On
        * `ldap` - LDAP
    TierEnum:
      enum:
        - free
        - pay-as-you-go
        - business
      type: string
      description: |-
        * `free` - Free
        * `pay-as-you-go` - Pay-as-you-go
        * `business` - Business
    APIV3FieldError:
      type: object
      properties:
        error:
          type: string
          description: Error code / translation key
        detail:
          type: string
          description: Human-readable description of the field error
      required:
        - detail
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.

````