Brainspace REST API

New
  • Published on Feb 2, 2026
  • 4 minute(s) read
Prev Next

With the release of Brainspace 7.3.0, Brainspace has migrated its REST API documentation and underlying specification from Swagger v2 to OpenAPI v3.0.1.

API Documentation and Specification URLs

HTML API Documentation

The HTML API documentation URL pattern remains the same: https://<your-brainspace-hostname>/rest/api-docs/index.html

Where:

  • <your-brainspace-hostname> is the base URL for your Brainspace environment (the same host you use for the Brainspace UI.)

What changed:

  • The HTML API documentation is now powered by an OpenAPI v3.0.1 specification instead of Swagger v2.

From an end-user perspective, the documentation URL and general UI are unchanged; only the underlying specification format has changed.

JSON Specification Endpoint

If you consume the raw API specification (for example, to generate client libraries,) the JSON path has changed:

  • Old JSON specification (Swagger v2)

    rest/api-docs-data/swagger.json

  • New JSON specification (OpenAPI v3.0.1)

    rest/api-docs-data/openapi.json

There full URL in your environment will therefore be:

https://<your-brainspace-hostname>/rest/api-docs-data/openapi.json

Any tooling, scripts, or build pipelines that fetch the specification must be updated to use the new openapi.json path.

Backwards-Incompatible API Changes

To produce a valid OpenAPI v3 specification, a small number of endpoints were corrected where datasetId appeared twice as a path parameter. These were specification-level fixes, but they are considered backwards-incompatible for tools and clients that relied on the old, incorrect parameter listings.

Affected Endpoints

The following endpoints previously had datasetId listed twice as a path parameter. In each case, the redundant datasetId parameter has been removed so that it appears only once: 

- GET    /dataset/{datasetId}/ingest/{ingestId}/examples
  Parameter change:
    - Delete duplicated datasetId in path

- GET    /dataset/{datasetId}/ingest/{ingestId}/fieldmap/default
  Parameter change:
    - Delete duplicated datasetId in path

- GET    /dataset/{datasetId}/ingest/{ingestId}/fieldmap/{fieldmapId}
  Parameter change:
    - Delete duplicated datasetId in path

- GET    /dataset/{datasetId}/ingest/{ingestId}/fields
  Parameter change:
    - Delete duplicated datasetId in path
    
- POST   /dataset/{datasetId}/ingest/{ingestId}/start
  Parameter change:
    - Delete duplicated datasetId in path

- GET    /dataset/{datasetId}/ingest/config
  Parameter change:
    - Delete duplicated datasetId in path

- PUT    /dataset/{datasetId}/ingest/config
  Parameter change:
    - Delete duplicated datasetId in path

- PUT    /dataset/{datasetId}/ingest/{ingestId}/fieldmap/textpath
  Parameter change:
    - Delete duplicated datasetId in path

- PUT    /dataset/{datasetId}/ingest/{ingestId}/fieldmap/validate
  Parameter change:
    - Delete duplicated datasetId in path
    
- GET    /dataset/{datasetId}/search/export
  Parameter change:
    - Delete duplicated datasetId in path

- POST   /dataset/{datasetId}/search/export
  Parameter change:
    - Delete duplicated datasetId in path

- PUT    /dataset/{datasetId}/ingest
  Parameter change:
    - Delete duplicated datasetId in path

- DELETE /dataset/{datasetId}/ingest/{ingestId}
  Parameter change:
    - Delete duplicated datasetId in path

- POST   /dataset/{datasetId}/ingest/{ingestId}
  Parameter change:
    - Delete duplicated datasetId in path

Important

The endpoint paths themselves have not changed. Only the parameter definitions in the API specification were corrected.

Example of the Change

Old Swagger JSON (with redundant datasetId)

"/dataset/{datasetId}/ingest/{ingestId}/fields": {"get": {
    "description": "",
    "operationId": "getIngestFields",
    "parameters": [
        {
            "format": "int32",
            "in": "path",
            "name": "datasetId",
            "required": true,
            "type": "integer"
        },
        {
            "format": "int32",
            "in": "path",
            "name": "datasetId",
            "required": true,
            "type": "integer"
        },
        {
            "format": "int32",
            "in": "path",
            "name": "ingestId",
            "required": true,
            "type": "integer"
        }
      ]
}}

New OpenAPI v3 JSON (with a single datasetId)

"/dataset/{datasetId}/ingest/{ingestId}/fields" : {
  "get" : {
    "operationId" : "getIngestFields",
    "parameters" : [ {
      "in" : "path",
      "name" : "datasetId",
      "required" : true,
      "schema" : {
        "type" : "integer",
        "format" : "int32",
        "example" : null
      }
    }, {
      "in" : "path",
      "name" : "ingestId",
      "required" : true,
      "schema" : {
        "type" : "integer",
        "format" : "int32",
        "example" : null
      }
    } ]
  }
}

Impact on API Users and Client Genrators

Direct HTTP Usage

If you call the Brainspace REST API directly (for example, using curl, Postman, or custom HTTP clients), no changes are required:

The paths, path variables, and query parameters you send are the same.

Request and response payloads are unchanged for the endpoints listed above.

Tools and Generated Clients

If you generate client libraries or use tooling that introspects the specification:

  1. Update the specification URL

    Change any references from:

    https://<your-brainspace-hostname>/rest/api-docs-data/swagger.json

    to:

    https://<your-brainspace-hostname>/rest/api-docs-data/openapi.json

  2. Regenerate clients and review parameter lists

    1. Endpoints that previously exposed two parameters will no expose only one.

    2. Regenerate your clients from the new OpenAPI v3 specification and review the generated method signatures or parameter objects for the affected endpoints.

    3. If any of your code depended on the old, incorrect duplication (for example, by inspecting the raw specification) you may need to adjust it to expect a single datasetId path parameter.

Summary of Required Actions

For most customers, the required steps are:

  1. Use the new OpenAPI v3 JSON specification path:

    • https://<your-brainspace-hostname>/rest/api-docs-data/openapi.json

  2. Regenerate any API clients or schemas from this new specification.

  3. Confirm ingest- and export-related endpoints use a single datasetId parameter in any generated code or tooling that depends on the specification.

Related articles