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

# Claromentis Integration

> Create and ingest Claromentis integration artifacts.

<Warning>
  **Upcoming release — Zylon 1.58**

  These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the [1.57 documentation](/en/v1.57/overview).
</Warning>

Claromentis integrations are stored as artifacts. The integration identifier used by these endpoints is the integration artifact ID.

## Prerequisites

Enable Claromentis at the instance level first. See [Claromentis integration setup](/en/v1.58/operator-manual/knowledge-base/claromentis).

## Create a Claromentis integration

Send credentials only in `private_props`; artifact responses do not return them.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Body | `project_id` | No | Project that owns the integration artifact. Omit it for an organization integration; that requires `AppAdmin` or higher. |
  | Body | `type` | Yes | Must be `Integration`. |
  | Body | `source` | Yes | Must be `Claromentis`. |
  | Body | `name` | Yes | Display name for the integration. |
  | Body | `props` | Yes | Public provider properties; use an empty object. |
  | Body | `props.metadata` | No | Optional provider metadata. |
  | Body | `private_props.username` | Yes | Claromentis username. |
  | Body | `private_props.password` | Yes | Claromentis password. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Integration",
    "source": "Claromentis",
    "name": "Claromentis",
    "props": {},
    "private_props": {
      "username": "{claromentis_username}",
      "password": "{claromentis_password}"
    }
  }'
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "id": "{integrationArtifactID}",
    "child_count": 0,
    "project_id": "{projectID}",
    "name": "Claromentis",
    "type": "Integration",
    "source": "Claromentis",
    "state": "Published",
    "ingest_status": "NotApplicable",
    "props": {},
    "keep_file_after_ingestion": true,
    "created_at": "2026-02-08T14:05:00Z",
    "updated_at": "2026-02-08T14:05:00Z"
  }
  ```
</Accordion>

## Update Claromentis credentials

Only the integration creator or an administrator can update private properties.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Claromentis integration artifact identifier. |
  | Body | `private_props.username` | Yes | Replacement username. |
  | Body | `private_props.password` | Yes | Replacement password. |
</Accordion>

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "private_props": {
      "username": "{claromentis_username}",
      "password": "{claromentis_password}"
    }
  }'
```

The response is the updated public artifact object. It does not contain `private_props`.

## Get the integration artifact

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Claromentis integration artifact identifier. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

The response uses the public artifact shape shown above and includes the persisted default project scope.

<Accordion title="Default scope in the GET response">
  ```json theme={null}
  {
    "scopes": [
      {
        "scope_type": "project",
        "scope_id": "{projectID}",
        "enabled": true,
        "ws_auto_select": false
      }
    ]
  }
  ```
</Accordion>

## Start an ingest sync

The endpoint returns a server-sent event (SSE) stream.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Claromentis integration artifact identifier. |
  | Body | `project_id` | Yes | Destination project identifier. |
  | Body | `folder_ids` | Yes | Claromentis folder identifiers to ingest. |
  | Body | `docs_ids` | Yes | Claromentis document identifiers to ingest. |
</Accordion>

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "folder_ids": ["knowledge-base"],
    "docs_ids": ["getting-started"]
  }'
```

<Accordion title="Example stream">
  ```text theme={null}
  event: SyncEvent
  data: {"type":"sync_started","current_artifact_count":6,"integration_item_count":24}

  event: SyncEvent
  data: {"type":"sync_completed"}
  ```
</Accordion>

## Errors and edge cases

* **400**: invalid provider fields or ingest parameters.
* **403**: connector not enabled, missing permission, or caller cannot update private properties.
* **404**: integration artifact or project not found, or they do not belong together.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.