---
title: "Brainspace REST API"
slug: "brainspace-rest-api"
tags: ["rest api", "open api", "swagger", "json", "datasetId"]
updated: 2026-02-02T18:32:38Z
published: 2026-02-02T18:32:38Z
canonical: "docs.revealdata.com/brainspace-rest-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revealdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Brainspace REST API

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:

```plaintext
- 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
```

> [!WARNING]
> **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`)

```plaintext
"/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`)

```plaintext
"/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.