Kibana Spaces API

openapi: 3.0.3
info:
  contact:
    name: Kibana Team
  description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.

    The API calls are stateless.

    Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the

    request.

    API requests return JSON output, which is a format that is machine-readable and works well for automation.


    To interact with Kibana APIs, use the following operations:


    - GET: Fetches the information.

    - PATCH: Applies partial modifications to the existing information.

    - POST: Adds new information.

    - PUT: Updates the existing information.

    - DELETE: Removes the information.


    You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.

    For example:


    ```

    GET kbn:/api/data_views

    ```


    For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).


    NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.


    ## Documentation source and versions


    This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.

    It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).


    This documentation contains work-in-progress information for future Elastic Stack releases.

    '
  title: Kibana APIs Actions Spaces API
  version: ''
  x-doc-license:
    name: Attribution-NonCommercial-NoDerivatives 4.0 International
    url: https://creativecommons.org/licenses/by-nc-nd/4.0/
  x-feedbackLink:
    label: Feedback
    url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
  variables:
    kibana_url:
      default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: Spaces
paths:
  /api/spaces/_resolve_copy_saved_objects_errors:
    post:
      description: 'Overwrite saved objects that are returned as errors from the copy saved objects to space API.<br/><br/>[Required authorization] Route required privileges: copySavedObjectsToSpaces.'
      operationId: post-spaces-resolve-copy-saved-objects-errors
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                compatibilityMode:
                  default: false
                  type: boolean
                createNewCopies:
                  default: true
                  type: boolean
                includeReferences:
                  default: false
                  type: boolean
                objects:
                  items:
                    additionalProperties: false
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                    required:
                    - type
                    - id
                  maxItems: 1000
                  type: array
                retries:
                  additionalProperties:
                    items:
                      additionalProperties: false
                      type: object
                      properties:
                        createNewCopy:
                          description: Creates new copies of the saved objects, regenerates each object ID, and resets the origin.
                          type: boolean
                        destinationId:
                          description: Specifies the destination identifier that the copied object should have, if different from the current identifier.
                          type: string
                        id:
                          description: The saved object identifier.
                          type: string
                        ignoreMissingReferences:
                          description: When set to true, any missing references errors are ignored.
                          type: boolean
                        overwrite:
                          default: false
                          description: When set to true, the saved object from the source space overwrites the conflicting object in the destination space.
                          type: boolean
                        type:
                          description: The saved object type.
                          type: string
                      required:
                      - type
                      - id
                    maxItems: 1000
                    type: array
                  type: object
              required:
              - retries
              - objects
            examples:
              resolveCopySavedObjectsRequestExample1:
                $ref: '#/components/examples/resolve_copy_saved_objects_request1'
              resolveCopySavedObjectsRequestExample2:
                $ref: '#/components/examples/resolve_copy_saved_objects_request2'
      responses:
        '200':
          description: 'OK: A successful request.'
          content:
            application/json:
              examples:
                resolveCopySavedObjectsResponseExample1:
                  $ref: '#/components/examples/copy_saved_objects_response1'
                resolveCopySavedObjectsResponseExample2:
                  $ref: '#/components/examples/copy_saved_objects_response2'
      summary: Resolve conflicts copying saved objects
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/spaces/_copy_saved_objects:
    post:
      description: 'It also allows you to automatically copy related objects, so when you copy a dashboard, this can automatically copy over the associated visualizations, data views, and saved Discover sessions, as required. You can request to overwrite any objects that already exist in the target space if they share an identifier or you can use the resolve copy saved objects conflicts API to do this on a per-object basis.<br/><br/>[Required authorization] Route required privileges: copySavedObjectsToSpaces.'
      operationId: post-spaces-copy-saved-objects
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                compatibilityMode:
                  default: false
                  description: Apply various adjustments to the saved objects that are being copied to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with copied saved objects. This option cannot be used with the `createNewCopies` option.
                  type: boolean
                createNewCopies:
                  default: true
                  description: Create new copies of saved objects, regenerate each object identifier, and reset the origin. When used, potential conflict errors are avoided.  This option cannot be used with the `overwrite` and `compatibilityMode` options.
                  type: boolean
                includeReferences:
                  default: false
                  description: When set to true, all saved objects related to the specified saved objects will also be copied into the target spaces.
                  type: boolean
                objects:
                  items:
                    additionalProperties: false
                    type: object
                    properties:
                      id:
                        description: The identifier of the saved object to copy.
                        type: string
                      type:
                        description: The type of the saved object to copy.
                        type: string
                    required:
                    - type
                    - id
                  maxItems: 1000
                  type: array
                overwrite:
                  default: false
                  description: When set to true, all conflicts are automatically overridden. When a saved object with a matching type and identifier exists in the target space, that version is replaced with the version from the source space. This option cannot be used with the `createNewCopies` option.
                  type: boolean
                spaces:
                  items:
                    description: The identifiers of the spaces where you want to copy the specified objects.
                    type: string
                  maxItems: 100
                  type: array
              required:
              - spaces
              - objects
            examples:
              copySavedObjectsRequestExample1:
                $ref: '#/components/examples/copy_saved_objects_request1'
              copySavedObjectsRequestExample2:
                $ref: '#/components/examples/copy_saved_objects_request2'
      responses:
        '200':
          description: 'OK: A successful request.'
          content:
            application/json:
              examples:
                copySavedObjectsResponseExample1:
                  $ref: '#/components/examples/copy_saved_objects_response1'
                copySavedObjectsResponseExample2:
                  $ref: '#/components/examples/copy_saved_objects_response2'
                copySavedObjectsResponseExample3:
                  $ref: '#/components/examples/copy_saved_objects_response3'
                copySavedObjectsResponseExample4:
                  $ref: '#/components/examples/copy_saved_objects_response4'
      summary: Copy saved objects between spaces
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/spaces/_disable_legacy_url_aliases:
    post:
      description: Disable one or more legacy URL aliases so that they no longer resolve to their target saved objects.
      operationId: post-spaces-disable-legacy-url-aliases
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                aliases:
                  items:
                    additionalProperties: false
                    type: object
                    properties:
                      sourceId:
                        description: The alias source object identifier. This is the legacy object identifier.
                        type: string
                      targetSpace:
                        description: The space where the alias target object exists.
                        type: string
                      targetType:
                        description: 'The type of alias target object. '
                        type: string
                    required:
                    - targetSpace
                    - targetType
                    - sourceId
                  maxItems: 1000
                  type: array
              required:
              - aliases
            examples:
              disableLegacyURLRequestExample1:
                $ref: '#/components/examples/disable_legacy_url_request1'
      responses:
        '204':
          description: Indicates a successful call.
      summary: Disable legacy URL aliases
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/spaces/_get_shareable_references:
    post:
      description: Collect references and space contexts for saved objects.
      operationId: post-spaces-get-shareable-references
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                objects:
                  items:
                    additionalProperties: false
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                    required:
                    - type
                    - id
                  maxItems: 1000
                  type: array
              required:
              - objects
            examples:
              getShareableReferencesRequestExample1:
                $ref: '#/components/examples/get_shareable_references_request1'
      responses:
        '200':
          description: Indicates a successful call.
          content:
            application/json:
              examples:
                getShareableReferencesResponseExample1:
                  $ref: '#/components/examples/get_shareable_references_response1'
      summary: Get shareable references
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/spaces/_update_objects_spaces:
    post:
      description: Update one or more saved objects to add or remove them from some spaces.
      operationId: post-spaces-update-objects-spaces
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                objects:
                  items:
                    additionalProperties: false
                    type: object
                    properties:
                      id:
                        description: The identifier of the saved object to update.
                        type: string
                      type:
                        description: The type of the saved object to update.
                        type: string
                    required:
                    - type
                    - id
                  maxItems: 1000
                  type: array
                spacesToAdd:
                  items:
                    description: The identifiers of the spaces the saved objects should be added to or removed from.
                    type: string
                  maxItems: 1000
                  type: array
                spacesToRemove:
                  items:
                    description: The identifiers of the spaces the saved objects should be added to or removed from.
                    type: string
                  maxItems: 1000
                  type: array
              required:
              - objects
              - spacesToAdd
              - spacesToRemove
            examples:
              updateObjectSpacesRequestExample1:
                $ref: '#/components/examples/update_saved_objects_spaces_request1'
      responses:
        '200':
          description: 'OK: A successful request.'
          content:
            application/json:
              examples:
                updateObjectSpacesResponseExample1:
                  $ref: '#/components/examples/update_saved_objects_spaces_response1'
      summary: Update saved objects in spaces
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/spaces/space:
    get:
      description: Retrieve all available Kibana spaces. The list includes only the spaces that the user is authorized to access.
      operationId: get-spaces-space
      parameters:
      - description: Specifies which authorization checks are applied to the API call. The default value is `any`.
        in: query
        name: purpose
        required: false
        schema:
          enum:
          - any
          - copySavedObjectsIntoSpace
          - shareSavedObjectsIntoSpace
          type: string
      - description: When enabled, the API returns any spaces the user is authorized to access in any capacity, each including the purposes for which the user is authorized. This is useful for identifying spaces the user can read but is not authorized for a given purpose. Without the security plugin, this parameter has no effect, because no authorization checks are performed. This parameter cannot be used together with the `purpose` parameter.
        in: query
        name: include_authorized_purposes
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Indicates a successful call.
          content:
            application/json:
              examples:
                getSpacesResponseExample1:
                  $ref: '#/components/examples/get_spaces_response1'
                getSpacesResponseExample2:
                  $ref: '#/components/examples/get_spaces_response2'
      summary: Get all spaces
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
    post:
      description: Create a new Kibana space.
      operationId: post-spaces-space
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                _reserved:
                  type: boolean
                color:
                  description: The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
                  type: string
                description:
                  description: A description for the space.
                  type: string
                disabledFeatures:
                  default: []
                  items:
                    description: The list of features that are turned off in the space.
                    type: string
                  maxItems: 100
                  type: array
                id:
                  description: The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.
                  type: string
                imageUrl:
                  description: The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.
                  type: string
                initials:
                  description: One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.
                  maxLength: 2
                  type: string
                name:
                  description: 'The display name for the space. '
                  minLength: 1
                  type: string
                projectRouting:
                  description: Cross-project search default routing configuration for this space. Controls whether searches are scoped to a single project or span multiple projects in serverless environments.
                  type: string
                solution:
                  enum:
                  - security
                  - oblt
                  - es
                  - classic
                  type: string
              required:
              - id
              - name
            examples:
              createSpaceRequest:
                $ref: '#/components/examples/create_space_request'
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                type: object
                properties:
                  _reserved:
                    type: boolean
                  color:
                    description: The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
                    type: string
                  description:
                    description: A description for the space.
                    type: string
                  disabledFeatures:
                    default: []
                    items:
                      description: The list of features that are turned off in the space.
                      type: string
                    maxItems: 100
                    type: array
                  id:
                    description: The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.
                    type: string
                  imageUrl:
                    description: The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.
                    type: string
                  initials:
                    description: One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.
                    maxLength: 2
                    type: string
                  name:
                    description: 'The display name for the space. '
                    minLength: 1
                    type: string
                  projectRouting:
                    description: Cross-project search default routing configuration for this space. Controls whether searches are scoped to a single project or span multiple projects in serverless environments.
                    type: string
                  solution:
                    enum:
                    - security
                    - oblt
                    - es
                    - classic
                    type: string
                required:
                - id
                - name
              examples:
                createSpaceResponseExample:
                  $ref: '#/components/examples/get_space_response'
          description: Indicates a successful call.
      summary: Create a space
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/spaces/space/{id}:
    delete:
      description: When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone.
      operationId: delete-spaces-space-id
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The space identifier.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Indicates a successful call.
        '404':
          description: Indicates that the request failed.
      summary: Delete a space
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
    get:
      description: Retrieve a single Kibana space by its identifier.
      operationId: get-spaces-space-id
      parameters:
      - description: The space identifier.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                getSpaceResponse:
                  description: A response that contains the full configuration for a single Kibana space.
                  summary: Get details about a marketing space
                  value:
                    color: '#aabbcc'
                    description: This is the Marketing Space
                    disabledFeatures: []
                    id: marketing
                    imageUrl: ''
                    initials: MK
                    name: Marketing
                    solution: es
              schema:
                additionalProperties: false
                type: object
                properties:
                  _reserved:
                    type: boolean
                  color:
                    description: The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
                    type: string
                  description:
                    description: A description for the space.
                    type: string
                  disabledFeatures:
                    default: []
                    items:
                      description: The list of features that are turned off in the space.
                      type: string
                    maxItems: 100
                    type: array
                  id:
                    description: The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.
                    type: string
                  imageUrl:
                    description: The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.
                    type: string
                  initials:
                    description: One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.
                    maxLength: 2
                    type: string
                  name:
                    description: 'The display name for the space. '
                    minLength: 1
                    type: string
                  projectRouting:
                    description: Cross-project search default routing configuration for this space. Controls whether searches are scoped to a single project or span multiple projects in serverless environments.
                    type: string
                  solution:
                    enum:
                    - security
                    - oblt
                    - es
                    - classic
                    type: string
                required:
                - id
                - name
          description: Indicates a successful call.
      summary: Get a space
      tags:
      - Spaces
      x-metaTags:
      - content: Kibana
        name: product_name
    put:
      description: Update an existing Kibana space.
      operationId: put-spaces-space-id
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The space identifier. You are unable to change the ID with the update operation.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                _reserved:
                  type: boolean
                color:
                  description: The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
                  type: string
                description:
                  description: A description for the space.
                  type: string
                disabledFeatures:
                  default: []
                  items:
                    description: The list of features that are turned off in the space.
                    type: string
                  maxItems: 100
                  type: array
                id:
                  description: The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.
                  type: string
                imageUrl:
                  description: The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.
                  type: string
                initials:
                  description: One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.
                  maxLength: 2
                  type: string
                name:
                  description: 'The display name for the space. '
                  minLength: 1
                  type: string
                projectRouting:
                  description: Cross-project search default routing configuration for this space. Controls whether searches are scoped to a single project or span multiple projects in serverless environments.
                  type: string
                solution:
                  enum:
                  - security
                  - oblt
                  - es
                  - classic
                  type: string
              required:
              - id
              - name
            examples:
              updateSpaceRequest:
                $ref: '#/components/examples/update_space_request'
      responses:
        '200':
          content:
            application/json:
              examples:
                updateSpaceResponse:
                  description: A response that contains the updated configuration of the Kibana space.
                  summary: Update the marketing space
                  value:
                    color: '#aabbcc'
                    description: An updated description for the Marketing Space
                    disabledFeatures: []
                    id: marketing
                    imageUrl: ''
                    initials: MK
                    name: Marketing
                    solution: es
              schema:
                additionalProperties: false
                type: object
                properties:
                  _reserved:
                    type: boolean
                  color:
                    description: The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
                    type: string
                  description:
                    description: A description for the space.
                    type: string
     

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-spaces-api-openapi.yml