> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/hyperledger-fabric/version-2.4/getting-started/catalyst-blockchain-manager-api.md).

# Catalyst Blockchain Manager API

For communication between your business application and a chaincode, Catalyst Blockchain Manager provides an API to invoke/query deployed chaincodes and subscribe for chaincode events.

{% hint style="info" %}
Catalyst Blockchain Manager API can be used by users who have an on-premise installation. Users who use Catalyst Blockchain Manager as a BaaS will be able to use the API in future releases.
{% endhint %}

{% hint style="info" %}
Catalyst Blockchain Manager supports two authorization types: **Basic** and **OpenID**. The authorization type is chosen during installation.
{% endhint %}

## Invoke Endpoint

**POST** `{domain}/api/v1/channels/{channelID}/cc/{chaincodeID}/invoke`

<details>

<summary>Path Parameters</summary>

| Parameter       | Type   | Description                                                                              |
| --------------- | ------ | ---------------------------------------------------------------------------------------- |
| `Domain`\*      | String | The name of the domain where the Catalyst Blockchain Platform Fabric service is deployed |
| `ChannelID`\*   | String | The name of the channel where the chaincode is committed                                 |
| `ChaincodeID`\* | String | The chaincode name                                                                       |

</details>

<details>

<summary>Request Body</summary>

| Field            | Type    | Description                                                                                                        |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `function`\*     | String  | The name of a chaincode function                                                                                   |
| `args`\*         | Array   | An array of function arguments                                                                                     |
| `transient_args` | Object  | Transient args — will reach the chaincode but won't stay in transaction records                                    |
| `is_init`        | Boolean | Indicates whether the init function call is required. Can only be `true` during the first operation with chaincode |

**Example:**

```json
{
    "args": ["data"],
    "transient_args": {
        "asset_properties": {
            "assetID": "99",
            "objectType": "art",
            "color": "black",
            "size": 500,
            "appraisedValue": 999
        }
    },
    "function": "CreateAsset",
    "is_init": false
}
```

</details>

<details>

<summary>Response</summary>

**200 OK:**

```json
{
  "proposal_response": {
    "chaincode_status": 0,
    "payload": "",
    "errors": [
      {
        "code": 0,
        "message": "string"
      }
    ]
  },
  "tx": {
    "id": "string",
    "validation_code": 0
  }
}
```

**Response fields:**

* `chaincode_status` — Response from chaincode. Possible values: `200` (success) or `500` (failure)
* `errors` — Status error returned from a peer. `message` equals the text in the exception the chaincode throws
* `payload` — Data returned on successful invocation from chaincode in base64
* `tx.id` — Transaction ID (unique per request)
* `tx.validation_code` — Must be `0` for any valid transaction

</details>

**Invoke example (Basic Auth):**

```bash
curl -X POST https://chaincodeinvokeexample.com/api/v1/channels/catbp/cc/helloworld/invoke \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic bG9naW46cGFzc3dvcmQK' \
  -d '{"function":"save","args":["John"],"is_init":false}'
```

{% hint style="info" %}
Generate a Basic Auth token: `echo {your_login}:{your_password} | base64`
{% endhint %}

## Query Endpoint

**POST** `{domain}/api/v1/channels/{channelID}/cc/{chaincodeID}/query`

Same path and body parameters as Invoke, with one addition:

| Field             | Type    | Description                                                      |
| ----------------- | ------- | ---------------------------------------------------------------- |
| `use_local_peers` | Boolean | Set to `true` to use only peers that belong to your organization |

**Query example (OpenID):**

```bash
curl -X POST https://chaincodequeryexample.com/api/v1/channels/catbp/cc/helloworld/query \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer b3BlbmlkOm9wZW5pZAo=' \
  -d '{"function":"get","args":["John"],"is_init":false}'
```

## Subscribe Endpoint

Server-Sent Events (SSE) that allows your client to receive automatic updates from the server via HTTP for a specific chaincode.

**GET** `{domain}/api/v1/channels/{channelID}/cc/{chaincodeID}/subscribe?startFrom={startFromValue}&eventFilter={eventFilterValue}`

<details>

<summary>Query Parameters</summary>

| Parameter     | Type    | Description                             |
| ------------- | ------- | --------------------------------------- |
| `startFrom`   | Integer | Block number (last block by default)    |
| `eventFilter` | String  | Regexp to filter only the needed events |

</details>

<details>

<summary>Response</summary>

```json
{
  "tx_id": "string",
  "chaincode_id": "string",
  "event_name": "string",
  "payload": "",
  "block_number": 0
}
```

| Field          | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `tx_id`        | The ID of the transaction in which the event was set        |
| `chaincode_id` | The ID of the chaincode that set the event                  |
| `event_name`   | The name of the chaincode event                             |
| `payload`      | The payload of the chaincode event in base64                |
| `block_number` | The block number in which the chaincode event was committed |

</details>

**Subscribe example (OpenID):**

```bash
curl -X GET https://chaincodesubscriptionexample.com/api/v1/channels/catbp/cc/helloworld/subscribe \
  -H 'Content-Type: text/event-stream' \
  -H 'Authorization: Bearer b3BlbmlkOm9wZW5pZAo='
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/hyperledger-fabric/version-2.4/getting-started/catalyst-blockchain-manager-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.