Connectors - Hexel Studio

Use a connector when you have data in S3 (or another external system) that changes frequently and you want agents to always search the current content — without uploading files by hand every time something updates. For instance, if your engineering team pushes updated runbooks to a bucket nightly, a connector ensures your on-call agent always retrieves the latest version. Connectors keep knowledge stores in sync with external systems. You configure a data source, run syncs on demand or on a schedule, and the platform ingests content automatically.

Available sources

Source	Status	Use for
Amazon S3	Available	Object storage buckets of documents.

Additional connector sources are on the roadmap. Only Amazon S3 is available today. Check the Console and Changelog for updates.

Key concepts

Term	Meaning
Data source	A configured connection to an external system.
Sync	A single ingestion run that reads, parses, chunks, and embeds content.
Schedule	How often a source syncs automatically.

Data source states

State	Meaning
`active`	Connected and ready to sync.
`paused`	Syncs suspended; resume to restart.
`error`	Connection or configuration issue.
`deleted`	Soft-deleted; no longer accessible.

Sync run states

State	Meaning
`pending`	Queued, not yet started.
`running`	Ingesting content.
`completed`	Finished successfully.
`failed`	Encountered an error; check sync details.

How it works

Create a data source

curl -X POST https://api.hexelstudio.com/data/v1/datasources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "docs-bucket",
    "source": "s3",
    "config": {
      "bucket": "my-company-docs",
      "region": "us-east-1",
      "max_object_size_mb": 50
    },
    "knowledge_store_id": "YOUR_STORE_ID"
  }'

Request parameters

string

required

Display name for the data source.

string

required

Connector type. Currently only s3.

object

required

Source-specific configuration.

string

required

S3 bucket name.

string

required

AWS region of the bucket (e.g., us-east-1).

integer

default:"50"

Maximum object size to ingest, in megabytes. Range: 1–500.

string

required

Target knowledge store for ingested content.

Response

string

Unique data source identifier.

string

Current state: active, paused, error, or deleted.

string

ISO 8601 creation timestamp.

Trigger a sync

curl -X POST https://api.hexelstudio.com/data/v1/datasources/YOUR_SOURCE_ID/sync \
  -H "Authorization: Bearer $TOKEN"

Pause and resume

# Pause
curl -X POST https://api.hexelstudio.com/data/v1/datasources/YOUR_SOURCE_ID/pause \
  -H "Authorization: Bearer $TOKEN"

# Resume
curl -X POST https://api.hexelstudio.com/data/v1/datasources/YOUR_SOURCE_ID/resume \
  -H "Authorization: Bearer $TOKEN"

List data sources

curl "https://api.hexelstudio.com/data/v1/datasources?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"

Get sync history

curl "https://api.hexelstudio.com/data/v1/datasources/YOUR_SOURCE_ID/syncs" \
  -H "Authorization: Bearer $TOKEN"

Errors

`code`	HTTP	When
`VALIDATION`	400	Missing `bucket`/`region`, or `max_object_size_mb` out of range (1–500).
`AUTH.PERMISSION_DENIED`	403	Missing `data-platform:connector:read` or `data-platform:connector:write`.
`RESOURCE.NOT_FOUND`	404	The data source doesn’t exist.

Security

Concern	Detail
Read permission	`data-platform:connector:read` — list, get, and view sync history.
Write permission	`data-platform:connector:write` — create, sync, pause, resume, update, and delete.
S3 access	Grant the platform read access to the S3 bucket you connect. Hexel does not write to your bucket.
Scoping	Data sources are scoped to your organization, workspace, and environment.
Storage	Ingested content is stored on platform-managed infrastructure, not back in your S3 bucket.

Troubleshooting

A sync fails or returns no documents

Confirm the bucket and region are correct and that the platform has read access to the bucket. Check the source’s sync history for the failing run; a failed sync records the cause.

Content is stale

A data source only refreshes when a sync runs. Schedule recurring syncs, or trigger one manually after the source changes.

Large objects are skipped

Objects above max_object_size_mb (default 50, max 500) are not ingested. Raise the limit on the data source if you need larger files.

Rate limits

10,000 requests per organization per hour. Pagination: page >= 1, page_size 1–100 (default 20).

Common errors

Code	Meaning
`404`	Data source not found or deleted.
`409`	Sync already running for this source.
`422`	Invalid config (e.g., max_object_size_mb out of range).
`429`	Rate limit exceeded.

IAM permissions for S3

The platform needs s3:GetObject and s3:ListBucket on the target bucket. Configure a cross-account IAM role or bucket policy granting these permissions to Hexel’s ingestion service. See Authentication for the trust policy.

Syncs

Monitor sync runs across your environment.

Knowledge Stores

Where synced content lands.

Documents & Uploads

Add one-off files directly.

Data Platform Overview

The full data model.

Next steps

Continue to Documents & Uploads.

​Available sources

​Key concepts

​Data source states

​Sync run states

​How it works

​Create a data source

​Request parameters

​Response

​Trigger a sync

​Pause and resume

​List data sources

​Get sync history

​Errors

​Security

​Troubleshooting

​Rate limits

​Related pages

Syncs

Knowledge Stores

Documents & Uploads

Data Platform Overview

​Next steps

Available sources

Key concepts

Data source states

Sync run states

How it works

Create a data source

Request parameters

Response

Trigger a sync

Pause and resume

List data sources

Get sync history

Errors

Security

Troubleshooting

Rate limits

Related pages

Next steps