> For the complete documentation index, see [llms.txt](https://docs.graph.build/EGeX4aTAJLlpg9Hh8kfl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graph.build/EGeX4aTAJLlpg9Hh8kfl/graph.build-studio/studio-api-endpoints.md).

# Studio API Endpoints

This guide shows how to create an API token and use the Graph.Build public APIs. You can use these endpoints to browse and download ontologies, export Studio diagrams, import external vocabularies, and connect an AI assistant over MCP.

### Contents

* [Before you start](#before-you-start)
* [Get an API token](#get-an-api-token)
* [Make your first request](#make-your-first-request)
* [What you can do with the API](#what-you-can-do-with-the-api)
* [Endpoint quick reference](#endpoint-quick-reference)
* [Ontology API](#ontology-api)
* [Studio export API](#studio-export-api)
* [Import external vocabularies](#import-external-vocabularies)
* [MCP (for AI assistants)](#mcp-for-ai-assistants)
* [Understanding errors](#understanding-errors)

***

### Before you start

You will need:

* The base URL of your Graph.Build instance (ask your administrator if you do not have it)
* An **Admin** or **Super Admin** account in Graph.Build Studio

All public API URLs start with:

```
https://<your-graphbuild-host>/api
```

For example, if your Studio is available at `https://studio.example.com`, the API base is:

```
https://studio.example.com/api
```

***

### Get an API token

API tokens let applications and scripts call Graph.Build without signing in through the browser. Each token belongs to an Admin or Super Admin user, starts with `gb_`, and has an expiry date you choose.

**Important:** The full token is shown only once. Copy it somewhere safe as soon as it appears.

#### Steps in Studio

1. Sign in to Graph.Build Studio as an **Admin** or **Super Admin**.
2. Open the **Admin Panel**.
3. Find the user who should own the token (must be Admin or Super Admin).
4. Click the key icon to **Generate API Token** (or **Renew API Token** if that user already has one).
5. Choose how long the token should last:
   * 1 day
   * 1 week
   * 1 month
   * 6 months
   * 12 months
6. Confirm with your username and password when asked.
7. Copy the token and store it securely.

#### Good to know

* Only Admin and Super Admin users can have API tokens.
* If a user already has a token, generate a new one with **Renew**. That replaces the old token, which stops working immediately.
* Tokens last at most 12 months.
* Treat the token like a password. Do not commit it to source control or share it in chat.

***

### Make your first request

Add your token to every API call using the `Authorization` header:

```
Authorization: Bearer gb_<your-token>
```

Example (replace the host and token with your values):

```bash
curl -s "https://studio.example.com/api" \
  -H "Authorization: Bearer gb_<your-token>"
```

If the token is valid, you receive a short JSON response with links to available API resources.

***

### What you can do with the API

| Area                       | What it is for                                                                                 | Who can use it                                                                           |
| -------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Ontology API               | Discover, browse, search, and download published ontologies                                    | Anyone with a valid API token                                                            |
| Studio export API          | List diagrams and export ontology, mapping, or DDL definitions                                 | Listing: any token user with access to the diagrams. Exports: Admin or Super Admin token |
| External vocabulary import | Upload a business glossary (currently Ab Initio) for use in Studio                             | Anyone with a valid API token                                                            |
| MCP                        | Connect an AI assistant to explore ontologies, read Studio projects, and edit ontology designs | Same `gb_` Bearer token as `/api` (Admin or Super Admin)                                 |

***

### Endpoint quick reference

All `/api` paths below require an API token unless noted. Path parameters such as `{ontologyId}` and `{iri}` must be double URL-encoded (see Useful conventions).

#### Ontology API

| Method | Path                                                     | Description                                   |
| ------ | -------------------------------------------------------- | --------------------------------------------- |
| `GET`  | `/api`                                                   | Discover available API resources              |
| `GET`  | `/api/ontologies`                                        | List published ontologies (paginated)         |
| `GET`  | `/api/ontologies?ontologyId=…` / `?ontologyURI=…`        | Download one or more ontologies as RDF        |
| `GET`  | `/api/ontologies/{ontologyId}`                           | Download a single ontology as RDF             |
| `GET`  | `/api/ontologies/{ontologyId}/classes/roots`             | List top-level classes                        |
| `GET`  | `/api/ontologies/{ontologyId}/classes/{iri}/children`    | List direct subclasses                        |
| `GET`  | `/api/ontologies/{ontologyId}/classes/{iri}/parents`     | List direct parent classes                    |
| `GET`  | `/api/ontologies/{ontologyId}/classes/{iri}/ancestors`   | List all ancestor classes                     |
| `GET`  | `/api/ontologies/{ontologyId}/classes/{iri}/descendants` | List all descendant classes                   |
| `GET`  | `/api/ontologies/{ontologyId}/properties/roots`          | List top-level properties                     |
| `GET`  | `/api/ontologies/{ontologyId}/properties/{iri}/children` | List child properties                         |
| `GET`  | `/api/ontologies/{ontologyId}/properties/{iri}/parents`  | List parent properties                        |
| `GET`  | `/api/ontologies/{ontologyId}/search`                    | Search classes and/or properties              |
| `GET`  | `/api/ontologies/{ontologyId}/resources/{iri}/cbd`       | Get a Concise Bounded Description (N-Triples) |

#### Studio export API

| Method | Path                                   | Description            | Notes                                            |
| ------ | -------------------------------------- | ---------------------- | ------------------------------------------------ |
| `GET`  | `/api/visualizations/ontologies`       | List ontology diagrams | Token user must be able to see the diagram       |
| `GET`  | `/api/visualizations/mappings`         | List mapping diagrams  | Token user must be able to see the diagram       |
| `GET`  | `/api/getCurrentOntologyDefinition`    | Export ontology Turtle | Admin or Super Admin token; requires `diagramId` |
| `GET`  | `/api/getCurrentMappingDefinition`     | Export mapping Turtle  | Admin or Super Admin token; requires `diagramId` |
| `GET`  | `/api/getCurrentSpannerDDLDefinition`  | Export Spanner DDL     | Admin or Super Admin token; requires `diagramId` |
| `GET`  | `/api/getCurrentBigQueryDDLDefinition` | Export BigQuery DDL    | Admin or Super Admin token; requires `diagramId` |

#### External vocabulary import

| Method | Path                                | Description                                                |
| ------ | ----------------------------------- | ---------------------------------------------------------- |
| `POST` | `/api/import/external-vocabularies` | Import an Ab Initio glossary (`sourceSystemType=AbInitio`) |

#### MCP (AI assistants)

These paths are on `/mcp`, not under `/api`. They use the same Bearer API token as `/api`.

| Method   | Path   | Description                                            |
| -------- | ------ | ------------------------------------------------------ |
| `POST`   | `/mcp` | JSON-RPC calls (initialize, tools, resources, prompts) |
| `GET`    | `/mcp` | Server-sent event notifications                        |
| `DELETE` | `/mcp` | End a session                                          |

The sections below describe parameters, response shapes, and examples for each group.

***

### Ontology API

Use these endpoints to work with ontologies published in Graph.Build. Responses for browsing and search use a structured JSON format (JSON-HAL) with pagination and navigation links. When you download ontology content, you can choose the RDF format you prefer.

#### Useful conventions

**Pagination**

List endpoints accept:

| Parameter | Default | Meaning                   |
| --------- | ------- | ------------------------- |
| `page`    | `0`     | Page number (starts at 0) |
| `size`    | `20`    | Number of items per page  |

**Choosing a download format**

When retrieving ontology content, set the `Accept` header to one of:

| Format           | Accept value            |
| ---------------- | ----------------------- |
| Turtle (default) | `text/turtle`           |
| N-Triples        | `application/n-triples` |
| JSON-LD          | `application/ld+json`   |
| RDF/XML          | `application/rdf+xml`   |

You can also request compressed responses with `Accept-Encoding: gzip`.

**Encoding ontology and resource IDs in the URL**

Ontology and resource identifiers often contain characters such as `/`, `:`, and `#`. When they appear in the URL path, encode them **twice** so the server can route the request correctly.

Example for the ontology ID `https://schema.org/`:

1. First encode → `https%3A%2F%2Fschema.org%2F`
2. Second encode → `https%253A%252F%252Fschema.org%252F`
3. Use in the path → `/api/ontologies/https%253A%252F%252Fschema.org%252F`

Most programming languages provide a URL-encode function you can call twice.

#### Endpoints

**Discover the API — `GET /api`**

Returns links to the main API resources. A good first call to confirm your token works.

```bash
curl -s "https://studio.example.com/api" \
  -H "Authorization: Bearer gb_<your-token>"
```

**List published ontologies — `GET /api/ontologies`**

Returns a page of ontologies available on your instance.

| Parameter | Required | Description               |
| --------- | -------- | ------------------------- |
| `page`    | No       | Page number (default `0`) |
| `size`    | No       | Page size (default `20`)  |

Each ontology entry includes identifiers, labels, a short description, and links you can follow for more detail.

**Download one or more ontologies — `GET /api/ontologies`**

Use the same path with query parameters to download ontology content instead of the catalogue:

| Parameter     | Required     | Description                                          |
| ------------- | ------------ | ---------------------------------------------------- |
| `ontologyId`  | One of these | Internal ontology graph identifier (can be repeated) |
| `ontologyURI` | One of these | Public ontology URI (can be repeated)                |
| `Accept`      | No           | Desired RDF format (see table above)                 |

```bash
curl -s "https://studio.example.com/api/ontologies?ontologyURI=https://schema.org/" \
  -H "Authorization: Bearer gb_<your-token>" \
  -H "Accept: text/turtle"
```

**Download a single ontology — `GET /api/ontologies/{ontologyId}`**

Downloads the full content of one ontology. Replace `{ontologyId}` with the double-encoded identifier. Choose the format with the `Accept` header.

**Browse classes**

| Method | Path                                                     | Description            |
| ------ | -------------------------------------------------------- | ---------------------- |
| `GET`  | `/api/ontologies/{ontologyId}/classes/roots`             | Top-level classes      |
| `GET`  | `/api/ontologies/{ontologyId}/classes/{iri}/children`    | Direct subclasses      |
| `GET`  | `/api/ontologies/{ontologyId}/classes/{iri}/parents`     | Direct parent classes  |
| `GET`  | `/api/ontologies/{ontologyId}/classes/{iri}/ancestors`   | All ancestor classes   |
| `GET`  | `/api/ontologies/{ontologyId}/classes/{iri}/descendants` | All descendant classes |

All of these support `page` and `size`. Class entries include the IRI, label, description, synonyms, and whether the class has children.

**Browse properties**

| Method | Path                                                     | Description          |
| ------ | -------------------------------------------------------- | -------------------- |
| `GET`  | `/api/ontologies/{ontologyId}/properties/roots`          | Top-level properties |
| `GET`  | `/api/ontologies/{ontologyId}/properties/{iri}/children` | Child properties     |
| `GET`  | `/api/ontologies/{ontologyId}/properties/{iri}/parents`  | Parent properties    |

All of these support `page` and `size`. Property entries include a `propertyType` of `objectProperty`, `datatypeProperty`, or `annotationProperty`.

**Search within an ontology — `GET /api/ontologies/{ontologyId}/search`**

| Parameter      | Required | Description                                 |
| -------------- | -------- | ------------------------------------------- |
| `q`            | Yes      | Search text                                 |
| `type`         | No       | `classes`, `properties`, or `all` (default) |
| `page`, `size` | No       | Pagination                                  |

```bash
curl -s "https://studio.example.com/api/ontologies/<double-encoded-id>/search?q=Person&type=classes" \
  -H "Authorization: Bearer gb_<your-token>"
```

**Get a resource description — `GET /api/ontologies/{ontologyId}/resources/{iri}/cbd`**

Returns a Concise Bounded Description (CBD) for a class or property as N-Triples. Both `{ontologyId}` and `{iri}` must be double-encoded in the path.

***

### Studio export API

These endpoints let you list diagrams from Studio and export their definitions. You only see diagrams that are public, owned by the token user, or shared with that user.

Exporting definitions requires an **Admin** or **Super Admin** token.

#### List diagrams

**Ontology diagrams — `GET /api/visualizations/ontologies`**

Returns the ontology diagrams available to the token user.

Example response:

```json
[
  {
    "id": 12,
    "name": "Customer Ontology",
    "visType": "ONTOLOGY",
    "graphType": "...",
    "propertyGraphImplementation": "...",
    "spannerGraphDataModel": "..."
  }
]
```

Use the `id` value as `diagramId` when exporting.

**Mapping diagrams — `GET /api/visualizations/mappings`**

Returns mapping diagrams (structured, SQL, and RESTful) available to the token user. The response shape matches the ontology list above.

#### Export definitions

Every export endpoint needs a `diagramId` query parameter.

| Method | Path                                   | Returns    | Description                                     |
| ------ | -------------------------------------- | ---------- | ----------------------------------------------- |
| `GET`  | `/api/getCurrentOntologyDefinition`    | Turtle     | Ontology definition for a diagram               |
| `GET`  | `/api/getCurrentMappingDefinition`     | Turtle     | Mapping definition for a diagram                |
| `GET`  | `/api/getCurrentSpannerDDLDefinition`  | Plain text | Spanner DDL generated from an ontology diagram  |
| `GET`  | `/api/getCurrentBigQueryDDLDefinition` | Plain text | BigQuery DDL generated from an ontology diagram |

**Ontology definition — `GET /api/getCurrentOntologyDefinition`**

| Parameter         | Required | Description                                                  |
| ----------------- | -------- | ------------------------------------------------------------ |
| `diagramId`       | Yes      | Ontology diagram ID from the list endpoint                   |
| `ontologyProfile` | No       | `studio` (default), `spannerPhysical`, or `bigqueryPhysical` |

```bash
curl -s "https://studio.example.com/api/getCurrentOntologyDefinition?diagramId=12&ontologyProfile=studio" \
  -H "Authorization: Bearer gb_<your-token>"
```

**Mapping definition — `GET /api/getCurrentMappingDefinition`**

| Parameter               | Required | Description                                          |
| ----------------------- | -------- | ---------------------------------------------------- |
| `diagramId`             | Yes      | Mapping diagram ID                                   |
| `useTemplatedSqlConfig` | No       | Set to `true` to include templated SQL configuration |

**Spanner DDL — `GET /api/getCurrentSpannerDDLDefinition`**

| Parameter   | Required | Description         |
| ----------- | -------- | ------------------- |
| `diagramId` | Yes      | Ontology diagram ID |

**BigQuery DDL — `GET /api/getCurrentBigQueryDDLDefinition`**

| Parameter   | Required | Description                               |
| ----------- | -------- | ----------------------------------------- |
| `diagramId` | Yes      | Ontology diagram ID                       |
| `location`  | No       | BigQuery location (default `us-central1`) |

***

### Import external vocabularies

You can upload a business glossary so it becomes available for browsing and use in Graph.Build Studio. Ab Initio glossary exports are supported today.

**`POST /api/import/external-vocabularies`**

| Parameter          | Required | Description    |
| ------------------ | -------- | -------------- |
| `sourceSystemType` | Yes      | Use `AbInitio` |

Send the glossary as a JSON array in the request body. Each item wraps either a vocabulary group (`BizTermGroup`) or a term (`BizTerm`).

```bash
curl -X POST "https://studio.example.com/api/import/external-vocabularies?sourceSystemType=AbInitio" \
  -H "Authorization: Bearer gb_<your-token>" \
  -H "Content-Type: application/json" \
  -d @abinitio-export.json
```

A successful import returns `201` with a summary, for example:

```json
{
  "sourceSystemType": "AbInitio",
  "vocabularyCount": 2,
  "termCount": 150,
  "namedGraphs": [
    "https://graph.build/external/AbInitio/vocabulary/..."
  ]
}
```

If you import the same vocabulary again, triples are posted into the same named graph. The importer currently **appends** (it does not clear the graph first), so clear the graph out of band if you need a clean replace.

#### Expected JSON shape (Ab Initio)

The body is an array. Groups and terms can appear in any order:

```json
[
  {
    "BizTermGroup": {
      "BizTermGroup": "PII_Dictionary",
      "BizTermGroupUUID": "cb4b633b-5dcd-4a51-ba25-973a19159b0e-1001",
      "Description": "Sample PII dictionary",
      "Division": "Global",
      "ParentBizTermGroup": null,
      "xSDReferenceData": null
    }
  },
  {
    "BizTerm": {
      "BizTerm": "Postal Address",
      "BizTermUUID": "...",
      "BizTermGroup": "PII_Dictionary",
      "ParentBizTerm": "Address",
      "Description": "An address used for postal delivery"
    }
  }
]
```

| Field              | Where         | Required | Meaning                                         |
| ------------------ | ------------- | -------- | ----------------------------------------------- |
| `BizTermGroup`     | Group         | Yes      | Vocabulary name                                 |
| `BizTermGroupUUID` | Group         | Yes      | Stable ID used to identify the vocabulary       |
| `Description`      | Group or term | No       | Human-readable description                      |
| `BizTerm`          | Term          | Yes      | Term label                                      |
| `BizTermUUID`      | Term          | Yes      | Stable term ID                                  |
| `BizTermGroup`     | Term          | Yes      | Name of the parent vocabulary group             |
| `ParentBizTerm`    | Term          | No       | Parent term label (builds a hierarchy when set) |

After a successful import, the vocabulary is available in Studio for browsing and use on diagrams.

***

### MCP (for AI assistants)

Graph.Build also exposes a Model Context Protocol (MCP) endpoint at `/mcp`. An AI assistant can use it to discover ontologies, search classes and properties, read the projects and data sources you can open, and edit or create ontology designs.

For how to connect a client, see [MCP Server](/EGeX4aTAJLlpg9Hh8kfl/graph.build-studio/mcp-server.md). For how to change a model, see [Editing designs](/EGeX4aTAJLlpg9Hh8kfl/graph.build-studio/mcp-server/editing-designs.md). For the catalogue of tools, resources, and prompts, see [Tools, resources, and prompts](/EGeX4aTAJLlpg9Hh8kfl/graph.build-studio/mcp-server/tools-resources-and-prompts.md).

| Method   | Path   | Purpose                                                     |
| -------- | ------ | ----------------------------------------------------------- |
| `POST`   | `/mcp` | Main JSON-RPC calls (initialize, tools, resources, prompts) |
| `GET`    | `/mcp` | Server-sent event notifications                             |
| `DELETE` | `/mcp` | End a session                                               |

**Auth model:**

* **Inbound `/mcp`** — same `Authorization: Bearer gb_…` token as `/api` (Admin or Super Admin). Missing or invalid tokens return HTTP `401` before JSON-RPC runs.
* Generate the token in the Admin Panel (shown once). Put it on every MCP request.

These paths are on `/mcp`, not under `/api`.

***

### Understanding errors

#### Authentication failed

If the token is missing, wrong, or expired:

```json
{
  "error": "Authentication failed. The request could not be authenticated."
}
```

HTTP status: `401`. Generate or renew a token in the Admin Panel and try again.

#### Common status codes

| Status | What it usually means                                                                                                                   |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | A required parameter is missing or a value is invalid                                                                                   |
| `401`  | Your API token is missing, invalid, or expired                                                                                          |
| `403`  | Your token is valid, but you are not allowed to do this (for example, exporting without an Admin token, or a diagram you cannot access) |
| `404`  | The diagram or ontology could not be found                                                                                              |
| `409`  | An API token already exists for that user — renew it instead of creating a new one                                                      |