--- title: "Create or Update Export Configuration" method: POST path: "/public/v1/enterprise-export/scores/config" tags: ["Scores - Enterprise Export"] --- # Create or Update Export Configuration `POST /public/v1/enterprise-export/scores/config` Create a new export configuration or update the existing one for the authenticated user. This endpoint allows you to configure automated score export jobs that will calculate and export scores for your specified collections, targets, and perspectives at regular intervals. **Upsert Behavior:** - If no configuration exists for the user, a new configuration will be created - If a configuration already exists, it will be completely replaced with the new values - This is an idempotent operation - calling it multiple times with the same data produces the same result - Each user can have only one export configuration at a time **Configuration Fields:** *Run Interval (`runInterval`):* - **Optional field** - defaults to `WEEKLY` if not specified - Valid values: `SIX_HOURS`, `TWELVE_HOURS`, `DAILY`, `WEEKLY` - Determines how frequently the export job executes: - `SIX_HOURS`: Every 6 hours (minimum interval) - `TWELVE_HOURS`: Every 12 hours - `DAILY`: Once every 24 hours - `WEEKLY`: Once every 168 hours (7 days) - The scheduler checks periodically, so execution may occur shortly after the interval elapses *Enabled State (`enabled`):* - **Required field** - must be explicitly set to `true` or `false` - When `true`: Job will automatically run based on the configured `runInterval` - When `false`: Job will not execute, even if the interval has elapsed - You can disable a job without deleting the configuration *Collections (`collectionIds`):* - **Required field** - must be provided (can be empty array `[]`) - List of Prewave Collection IDs to include in the export - All targets within these collections will be included in the export - Collections are validated for user access when the job executes (not at configuration time) - Empty collections or collections with no accessible targets will be skipped during execution - **To get collection IDs**: Use endpoints from the Collections API: - `GET /public/v1/collections` - List all accessible collections (returns `id` field for each collection) - `GET /public/v1/collections/{collectionId}` - Get a specific collection by ID *Targets (`targetIds`):* - **Required field** - must be provided (can be empty array `[]`) - List of specific Target IDs to include in addition to collection targets - Targets from collections and individual target IDs are combined (union operation) with no duplicates - Useful for including specific targets that may not be in any collection - Target access is validated when the job executes - **To get target IDs**: Use endpoints from the Suppliers API: - `GET /public/v2/suppliers/sites` - List all supplier sites (returns `prewaveTargetId` field for each supplier) - `GET /public/v2/suppliers/sites/find-by-identifier?prewaveId={targetId}` - Get a specific supplier by ID *Perspectives (`perspectiveIds`):* - **Required field** - must be provided and **must contain at least one perspective ID** (cannot be empty array `[]`) - List of Perspective IDs for which scores should be calculated - ⚠️ **Critical**: If `perspectiveIds` is empty, the configuration will be saved successfully, but **no scores will be generated** during job execution. The endpoint will not return an error, but the export job will produce no results. - Scores are calculated for each combination of (target × perspective) - All specified perspectives must be accessible to the user (validated at execution time) - Example: If you have 10 targets and 2 perspectives, 20 score calculations will be performed *Components (`includeComponents`):* - **Required field** - must be explicitly set to `true` or `false` - When `true`: Export results include detailed score components and subcomponents - When `false`: Only top-level scores and risk levels are included - Enabling components increases response size but provides granular score breakdowns - Affects the structure of data returned by `GET /public/v1/enterprise-export/scores` **Validation and Execution:** *Configuration-Time Validation:* - Basic request validation (JSON format, field types) - Run interval must be one of the valid enum values - All required fields must be present *Execution-Time Validation:* - Collection access is validated when the job runs (not when configuration is saved) - Target access is validated during execution - Perspective access is validated during execution - If validation fails during execution, the job will fail and errors will be available via `GET /public/v1/enterprise-export/scores/errors` **After Configuration:** 1. **Immediate Effect**: Configuration is saved immediately upon successful request 2. **Job Scheduling**: If `enabled` is `true`, the job will be scheduled based on: - The configured `runInterval` - The time since the last execution (if any) 3. **First Execution**: If this is a new configuration or the first time enabling: - The job will run when the scheduler next checks (typically within an hour) - Or immediately if the interval has already elapsed 4. **Results Availability**: After successful execution: - Use `GET /public/v1/enterprise-export/scores` to retrieve score results - Use `GET /public/v1/enterprise-export/scores/errors` to check for any errors 5. **Configuration Updates**: Use `GET /public/v1/enterprise-export/scores/config` to verify your configuration **Best Practices:** - **Start Small**: Begin with a small set of collections/targets and perspectives to test the configuration - **Monitor Results**: Check the scores endpoint after the first execution to verify everything works - **Check Errors**: Regularly review the errors endpoint to identify any issues - **Frequency**: Choose an appropriate `runInterval` based on your data freshness requirements - **Components**: Only enable `includeComponents` if you need detailed score breakdowns (increases data size) - **Empty Lists**: You can provide empty arrays for `collectionIds` or `targetIds` if you only want to use one type. However, **`perspectiveIds` must contain at least one ID** - if empty, no scores will be generated. **Important Notes:** - The configuration is user-specific - each user manages their own export configuration - Jobs run asynchronously - execution may take time depending on the number of targets and perspectives - Previous configuration is completely replaced - all fields are updated, not merged - Validation happens at execution time, not configuration time - invalid IDs will cause execution failures - If a job fails due to access issues, fix the configuration and the next scheduled run will attempt again **Required Permission**: `ACCESS_ENTERPRISE_EXPORT_API` ## Request body - PublicScoreExecutionConfig - `runInterval` 'SIX_HOURS' | 'TWELVE_HOURS' | 'DAILY' | 'WEEKLY', required — Defines the time interval for running the export job. Options include SIX_HOURS, TWELVE_HOURS, DAILY, and WEEKLY. Defaults to WEEKLY if not specified. - `enabled` boolean, required — Indicates whether the export job is enabled. If false, the job will not run. - `collectionIds` integer[], required — List of Prewave Collection IDs to include in the export job. - `targetIds` integer[], required — List of Target IDs to include in the export job. - `perspectiveIds` integer[], required — List of Perspective IDs to include in the export job. - `includeComponents` boolean, required — Indicates whether to include score components and subcomponents in the export result. If true, components will be included. ## Response `200` Configuration successfully created or updated. The response contains the complete configuration that was saved, including any default values applied (e.g., runInterval defaults to WEEKLY if not specified). - PublicScoreExecutionConfig - `runInterval` 'SIX_HOURS' | 'TWELVE_HOURS' | 'DAILY' | 'WEEKLY', required — Defines the time interval for running the export job. Options include SIX_HOURS, TWELVE_HOURS, DAILY, and WEEKLY. Defaults to WEEKLY if not specified. - `enabled` boolean, required — Indicates whether the export job is enabled. If false, the job will not run. - `collectionIds` integer[], required — List of Prewave Collection IDs to include in the export job. - `targetIds` integer[], required — List of Target IDs to include in the export job. - `perspectiveIds` integer[], required — List of Perspective IDs to include in the export job. - `includeComponents` boolean, required — Indicates whether to include score components and subcomponents in the export result. If true, components will be included. ## Other responses - `400` — 400 Bad Request - Invalid request payload or validation errors. The request body is malformed, contains invalid data types, or has validation errors. - `403` — 403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource. - `404` — 404 Not Found - One or more collections, targets, or perspectives specified in the configuration were not found or are not accessible to the authenticated user. Note: This validation typically occurs during job execution, not at configuration time. However, if immediate validation is performed and resources are not accessible, this error will be returned. - `429` — 429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success. - `500` — 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed. --- [API](https://skmtc.net/prewave/apis/public-prewave-api.md) · [All operations](https://skmtc.net/prewave/apis/public-prewave-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prewave/public-prewave-api/revisions/466169815b78/schema)