Unimode Catalog Enrichment

Getting started

You need: your workspace's API key (shown once, when Unimode creates the workspace), the AWS account you registered with Unimode, an S3 bucket and folder for feeds, and one for results. Unimode never asks for AWS credentials: you create a role that Unimode may assume, limited to those two folders.

Every request goes to the base URL in API reference with your key:

Authorization: Bearer um_live_...

1. Create the access role

Download the CloudFormation template for your workspace:

GET /v1/integration/template

Deploy it in your AWS account (CloudFormation → Create stack → upload the template). Choose the input bucket and folder (feeds) and the output bucket and folder (results). If the buckets use a customer-managed KMS key, pass its ARN as KmsKeyArn. The stack creates the role UnimodeEnrichmentAccess-<stack name>. Only Unimode's service can assume it, and only with your workspace's external ID, which the template already contains.

2. Register the role

PUT /v1/integration
{"role_arn": "arn:aws:iam::111122223333:role/UnimodeEnrichmentAccess-feeds",
 "input_prefix": "s3://acme-feeds/unimode/",
 "output_prefix": "s3://acme-results/unimode-results/"}

Unimode assumes the role, lists the input folder, and writes (then deletes) a test object in the output folder. On success your workspace becomes active (GET /v1/me shows the status and, until then, the next setup step).

3. Upload a feed and start a run

Upload a JSON Lines file to the input folder (see Feed format), then:

POST /v1/runs
{"input": "s3://acme-feeds/unimode/2026-10/feed.jsonl",
 "output": "s3://acme-results/unimode-results/"}

The response is 202 with the run's ID. Follow it with GET /v1/runs/{run_id}; when it shows succeeded, the results are in <output>/<run_id>/. run.json is written last: when it exists, the delivery is complete.

Managing access