Prewave Scores - Enterprise Export API
Public API for managing enterprise export configurations and retrieving score data in Prewave's supply chain network.
OpenAPI Specification
openapi: 3.0.1
info:
title: Public Prewave Actions Scores - Enterprise Export API
description: 'Documentation of the Public Prewave API.
## What''s New
### Q1 2026 — Supplier Management, User Management, Actions and Feed
This quarter introduces major v2 upgrades, expanded administrative capabilities, and the new Actions API.
- **Core Releases:** Deployed Supplier Management API v2 and Feed API v2, alongside the all-new Actions API.
- **Enhanced Functionality:** Added robust identifier management, granular user and role configuration, and endpoints for managing supplier connection contacts.
- ⚠️ **Required Migration:** Legacy v1 endpoints for Suppliers and Sites Upsert have been deprecated. Developers must migrate existing integrations to v2 by **May 31, 2027** (original deadline was December 31, 2026).
📖 **[Read the Q1 2026 changelog](https://docs.prewave.com/en/articles/699847-q1-2026-public-api-updates)**
### Q2 2026 — Supplier Screening and External Scores
We have expanded our v2 documentation to include comprehensive integration guidance for supplier screening and validation workflows and identifier-based external score ingestion.
- **New Capabilities:** Added support for optional post-onboarding screening and validation during the create event.
- **External Scores:** Batch POST for multiple supplier sites, per-site history GET, and event-type discovery GET (`/public/v1/scores/externals` and `/public/v1/scores/externals/event-types`). Documented in OpenAPI when enabled for your organization.
- **Developer Resources:** Published new integration examples and detailed identifier validation rules to streamline your implementation process.
📖 **[Read the Q2 2026 changelog](https://docs.prewave.com/en/articles/699849-q2-2026-public-api-updates)**
### Q3 2026 — Scores Webhooks
To support event-driven architectures and eliminate the need for continuous API polling, we are introducing webhooks for score state changes later this year.
- **Event-Driven Architecture:** Register webhook URLs to receive real-time HTTP payloads whenever a supplier''s score updates, so you can drive immediate mitigation responses without polling the API.
- **Availability:** Comprehensive OpenAPI specifications and payload schemas will be published closer to the release date.
- **Note:** Schemas and behaviors are subject to refinement prior to general availability.
Documentation updates will be provided prior to release.
### Q4 2026 — Feed V2
We are enhancing Feed API v2 with additional capabilities on top of the existing `GET /public/v2/feed` contract (see Q1 changelog and OpenAPI for the current Feed v2 integration).
- **Availability:** Details will be announced before release.
- **Note:** Schemas and behaviors are subject to refinement prior to the official release.
Documentation updates will be provided prior to release.
---
## Authentication
Prewave’s public api uses *API tokens* to authenticate against our RESTful service. We’ll provide you an *API-token* that each
endpoint needs present as a http header.
To pass the token in a request, simply add it as a header-parameter with
* key = X-Auth-Token
* value = api-token
See an example in curl below where the api-token would be 12345678-90ab-cdef-1234-567890abcdef
```
curl --request GET \
--url https://REPLACE_WITH_SERVER/public/v1/target/prewave/3975230/alerts \
--header ''X-Auth-Token: 12345678-90ab-cdef-1234-567890abcdef''
```
---
## Manage API Tokens
Before you can obtain your API token, you''ll need the credentials for your API user. These credentials will be
sent to you as part of the company-onboarding. If you haven''t got your credentials yet, please reach out to
your sales-contact at Prewave or contact us via info@prewave.ai
To generate an API Token, navigate to https://www.prewave.com/management/api and log in with the
credentials of your API user. Then click at the button "Create New" and use your new api-token authentication as a header parameter.
You can create multiple API tokens and also remove existing API tokens on https://www.prewave.com/management/api.
API tokens do not expire, therefore you have to maintain the list of API tokens you are using manually.
---
## Default Rate Limits
We have two types of default rate limits. For increased access, please contact customer success.
| Type | Requests per 10 seconds | Requests per Minute |
|-----------------------------------|-------------------------|---------------------|
| GET requests | 100 | 500 |
| POST, PUT, PATCH, DELETE requests | 20 | 100 |
'
version: '1.0'
servers:
- url: https://api.prewave.com
description: Production Environment
security:
- Token authentication: []
tags:
- name: Scores - Enterprise Export
description: Public API for managing enterprise export configurations and retrieving score data in Prewave's supply chain network.
paths:
/public/v1/enterprise-export/scores/config:
get:
tags:
- Scores - Enterprise Export
summary: Get Export Configuration
description: "\nRetrieve the current export configuration for the authenticated user.\n\nThis endpoint returns the user's active export job configuration, which determines:\n- Which collections, targets, and perspectives to include\n- How frequently the export job runs (interval)\n- Whether the job is currently enabled\n- Whether to include detailed score components and subcomponents\n\n**Configuration Behavior:**\n\n*Run Intervals:*\n- `SIX_HOURS`: Job runs every 6 hours (minimum interval)\n- `TWELVE_HOURS`: Job runs every 12 hours\n- `DAILY`: Job runs once every 24 hours\n- `WEEKLY`: Job runs once every 168 hours (7 days)\n- The scheduler checks for due executions periodically, so actual execution may occur shortly after the interval elapses\n\n*Enabled State:*\n- When `enabled` is `true`, the job will automatically run based on the configured `runInterval`\n- When `enabled` is `false`, the job will not execute, even if the interval has elapsed\n- Jobs only run if they are both enabled AND due based on the last execution time\n\n*Collections and Targets:*\n- `collectionIds`: List of Prewave Collection IDs. All targets within these collections will be included in the export\n- `targetIds`: List of specific Target IDs to include. These are combined with targets from collections (union operation)\n- Targets from collections and individual target IDs are merged together (no duplicates)\n- If a collection is empty or contains no accessible targets, it will be skipped during execution\n- **To get collection IDs**: Use endpoints from the Collections API:\n - `GET /public/v1/collections` - List all accessible collections (returns `id` field for each collection)\n - `GET /public/v1/collections/{collectionId}` - Get a specific collection by ID\n- **To get target IDs**: Use endpoints from the Suppliers API:\n - `GET /public/v2/suppliers/sites` - List all supplier sites (returns `prewaveTargetId` field for each supplier)\n - `GET /public/v2/suppliers/sites/find-by-identifier?prewaveId={targetId}` - Get a specific supplier by ID\n\n*Perspectives:*\n- `perspectiveIds`: List of Perspective IDs for which scores should be calculated\n- **Required for active configurations** - must contain at least one perspective ID when creating or updating a configuration\n- ⚠️ **Important**: If `perspectiveIds` is empty, the endpoint will accept the configuration but **no scores will be generated** during execution\n- In the default response (when no configuration exists), `perspectiveIds` will be empty (`[]`), indicating an incomplete/disabled configuration\n- Scores are calculated for each combination of (target × perspective)\n- All specified perspectives must be accessible to the user\n- Example: If you have 10 targets and 2 perspectives, 20 score calculations will be performed\n\n*Components:*\n- `includeComponents`: When `true`, the export results will include detailed score components and subcomponents\n- When `false`, only top-level scores and risk levels are included\n- Enabling components increases the response size but provides more granular score breakdowns\n\n**Response Format:**\n- If no configuration exists, a default configuration will be returned with:\n - Empty `collectionIds` and `targetIds` lists\n - Empty `perspectiveIds` list\n - `enabled` set to `false`\n - `runInterval` set to `WEEKLY`\n - `includeComponents` set to `false`\n- ⚠️ **Note**: While the default configuration shows `perspectiveIds` as empty, this is not a valid configuration for generating scores. You must provide at least one perspective ID when creating or updating the configuration, otherwise no scores will be generated during execution.\n- All configuration fields are returned as specified in the response schema\n- The `runInterval` field defaults to `WEEKLY` if not explicitly set\n\n**Using the Configuration:**\n\n1. **Check Configuration**: Use this endpoint to verify your current export configuration\n2. **Update Configuration**: Use `POST /public/v1/enterprise-export/scores/config` to create or update the configuration\n3. **Retrieve Results**: After a job executes, use `GET /public/v1/enterprise-export/scores` to retrieve score results\n4. **Check Errors**: Use `GET /public/v1/enterprise-export/scores/errors` to view any errors that occurred during execution\n\n**Important Notes:**\n- The configuration is user-specific - each user has their own export configuration\n- Jobs run asynchronously - execution may take time depending on the number of targets and perspectives\n- Results are only available after at least one successful execution has completed\n- If no results are available yet, `GET /public/v1/enterprise-export/scores` will return an empty page\n- Collection access is validated before execution - if you lack access to specified collections, the execution will fail\n- The last successful execution's results are always available via the scores endpoint\n\n**Required Permission**: `ACCESS_ENTERPRISE_EXPORT_API`\n "
operationId: getExportConfiguration
responses:
'200':
description: Configuration successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/PublicScoreExecutionConfig'
examples:
Active configuration:
summary: Sample active export configuration
description: An active configuration with collections, targets, and perspectives configured. The job will run automatically based on the WEEKLY interval.
value:
runInterval: WEEKLY
enabled: true
collectionIds:
- 123
- 456
- 789
targetIds:
- 102006215
- 101641243
- 10422185
perspectiveIds:
- 1
- 2
- 3
includeComponents: false
Disabled configuration:
summary: Configuration with job disabled
description: A configuration that exists but is disabled. The job will not run even if the interval has elapsed.
value:
runInterval: DAILY
enabled: false
collectionIds:
- 123
- 456
targetIds:
- 102006215
perspectiveIds:
- 1
includeComponents: true
Default configuration:
summary: Default configuration when none exists
description: The default configuration returned when no configuration has been created yet. The empty `perspectiveIds` array (`[]`) indicates an incomplete/disabled configuration. You must provide at least one perspective ID when creating or updating a configuration, otherwise no scores will be generated during execution.
value:
runInterval: WEEKLY
enabled: false
collectionIds: []
targetIds: []
perspectiveIds: []
includeComponents: false
High-frequency configuration:
summary: Configuration with frequent execution
description: A configuration set to run every 6 hours with components enabled for detailed score breakdowns.
value:
runInterval: SIX_HOURS
enabled: true
collectionIds:
- 123
targetIds:
- 102006215
- 101641243
perspectiveIds:
- 1
- 2
includeComponents: true
'403':
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 100,\n \"requestCount\": 100,\n \"limits\": [\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 500,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
post:
tags:
- Scores - Enterprise Export
summary: Create or Update Export Configuration
description: "\nCreate a new export configuration or update the existing one for the authenticated user.\n\nThis 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.\n\n**Upsert Behavior:**\n- If no configuration exists for the user, a new configuration will be created\n- If a configuration already exists, it will be completely replaced with the new values\n- This is an idempotent operation - calling it multiple times with the same data produces the same result\n- Each user can have only one export configuration at a time\n\n**Configuration Fields:**\n\n*Run Interval (`runInterval`):*\n- **Optional field** - defaults to `WEEKLY` if not specified\n- Valid values: `SIX_HOURS`, `TWELVE_HOURS`, `DAILY`, `WEEKLY`\n- Determines how frequently the export job executes:\n - `SIX_HOURS`: Every 6 hours (minimum interval)\n - `TWELVE_HOURS`: Every 12 hours\n - `DAILY`: Once every 24 hours\n - `WEEKLY`: Once every 168 hours (7 days)\n- The scheduler checks periodically, so execution may occur shortly after the interval elapses\n\n*Enabled State (`enabled`):*\n- **Required field** - must be explicitly set to `true` or `false`\n- When `true`: Job will automatically run based on the configured `runInterval`\n- When `false`: Job will not execute, even if the interval has elapsed\n- You can disable a job without deleting the configuration\n\n*Collections (`collectionIds`):*\n- **Required field** - must be provided (can be empty array `[]`)\n- List of Prewave Collection IDs to include in the export\n- All targets within these collections will be included in the export\n- Collections are validated for user access when the job executes (not at configuration time)\n- Empty collections or collections with no accessible targets will be skipped during execution\n- **To get collection IDs**: Use endpoints from the Collections API:\n - `GET /public/v1/collections` - List all accessible collections (returns `id` field for each collection)\n - `GET /public/v1/collections/{collectionId}` - Get a specific collection by ID\n\n*Targets (`targetIds`):*\n- **Required field** - must be provided (can be empty array `[]`)\n- List of specific Target IDs to include in addition to collection targets\n- Targets from collections and individual target IDs are combined (union operation) with no duplicates\n- Useful for including specific targets that may not be in any collection\n- Target access is validated when the job executes\n- **To get target IDs**: Use endpoints from the Suppliers API:\n - `GET /public/v2/suppliers/sites` - List all supplier sites (returns `prewaveTargetId` field for each supplier)\n - `GET /public/v2/suppliers/sites/find-by-identifier?prewaveId={targetId}` - Get a specific supplier by ID\n\n*Perspectives (`perspectiveIds`):*\n- **Required field** - must be provided and **must contain at least one perspective ID** (cannot be empty array `[]`)\n- List of Perspective IDs for which scores should be calculated\n- ⚠️ **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.\n- Scores are calculated for each combination of (target × perspective)\n- All specified perspectives must be accessible to the user (validated at execution time)\n- Example: If you have 10 targets and 2 perspectives, 20 score calculations will be performed\n\n*Components (`includeComponents`):*\n- **Required field** - must be explicitly set to `true` or `false`\n- When `true`: Export results include detailed score components and subcomponents\n- When `false`: Only top-level scores and risk levels are included\n- Enabling components increases response size but provides granular score breakdowns\n- Affects the structure of data returned by `GET /public/v1/enterprise-export/scores`\n\n**Validation and Execution:**\n\n*Configuration-Time Validation:*\n- Basic request validation (JSON format, field types)\n- Run interval must be one of the valid enum values\n- All required fields must be present\n\n*Execution-Time Validation:*\n- Collection access is validated when the job runs (not when configuration is saved)\n- Target access is validated during execution\n- Perspective access is validated during execution\n- If validation fails during execution, the job will fail and errors will be available via `GET /public/v1/enterprise-export/scores/errors`\n\n**After Configuration:**\n\n1. **Immediate Effect**: Configuration is saved immediately upon successful request\n2. **Job Scheduling**: If `enabled` is `true`, the job will be scheduled based on:\n - The configured `runInterval`\n - The time since the last execution (if any)\n3. **First Execution**: If this is a new configuration or the first time enabling:\n - The job will run when the scheduler next checks (typically within an hour)\n - Or immediately if the interval has already elapsed\n4. **Results Availability**: After successful execution:\n - Use `GET /public/v1/enterprise-export/scores` to retrieve score results\n - Use `GET /public/v1/enterprise-export/scores/errors` to check for any errors\n5. **Configuration Updates**: Use `GET /public/v1/enterprise-export/scores/config` to verify your configuration\n\n**Best Practices:**\n\n- **Start Small**: Begin with a small set of collections/targets and perspectives to test the configuration\n- **Monitor Results**: Check the scores endpoint after the first execution to verify everything works\n- **Check Errors**: Regularly review the errors endpoint to identify any issues\n- **Frequency**: Choose an appropriate `runInterval` based on your data freshness requirements\n- **Components**: Only enable `includeComponents` if you need detailed score breakdowns (increases data size)\n- **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.\n\n**Important Notes:**\n- The configuration is user-specific - each user manages their own export configuration\n- Jobs run asynchronously - execution may take time depending on the number of targets and perspectives\n- Previous configuration is completely replaced - all fields are updated, not merged\n- Validation happens at execution time, not configuration time - invalid IDs will cause execution failures\n- If a job fails due to access issues, fix the configuration and the next scheduled run will attempt again\n\n**Required Permission**: `ACCESS_ENTERPRISE_EXPORT_API`\n "
operationId: createOrUpdateExportConfiguration
requestBody:
description: Request payload containing the export job configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicScoreExecutionConfig'
required: true
responses:
'200':
description: 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).
content:
application/json:
schema:
$ref: '#/components/schemas/PublicScoreExecutionConfig'
examples:
Created configuration:
summary: Successfully created new configuration
description: Response after creating a new configuration. All fields are returned as saved.
value:
runInterval: WEEKLY
enabled: true
collectionIds:
- 123
- 456
targetIds:
- 102006215
- 101641243
perspectiveIds:
- 1
- 2
includeComponents: false
Updated configuration:
summary: Successfully updated existing configuration
description: Response after updating an existing configuration. The previous configuration was completely replaced.
value:
runInterval: DAILY
enabled: true
collectionIds:
- 789
- 101
targetIds:
- 10422185
perspectiveIds:
- 1
- 2
- 3
includeComponents: true
Configuration with default interval:
summary: Configuration with default WEEKLY interval
description: When runInterval is omitted, it defaults to WEEKLY in the response.
value:
runInterval: WEEKLY
enabled: true
collectionIds:
- 123
targetIds: []
perspectiveIds:
- 1
includeComponents: false
'400':
description: 400 Bad Request - Invalid request payload or validation errors. The request body is malformed, contains invalid data types, or has validation errors.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Invalid run interval:
summary: Invalid runInterval enum value
description: The runInterval value must be one of the valid enum values.
value:
code: validation_error
message: 'Invalid run interval. Must be one of: SIX_HOURS, TWELVE_HOURS, DAILY, WEEKLY'
details:
field: runInterval
value: INVALID_INTERVAL
Missing required field:
summary: Required field is missing
description: All required fields must be present in the request.
value:
code: validation_error
message: Required field 'enabled' is missing
solution: Include all required fields in the request
Invalid JSON:
summary: Request body is not valid JSON
description: The request body must be valid JSON format.
value:
code: invalid_request
message: 'JSON parse error: Unexpected character'
solution: Fix the JSON format
Invalid field type:
summary: Field has wrong data type
description: Fields must have the correct data types (e.g., enabled must be boolean, not string).
value:
code: validation_error
message: Invalid type for field 'enabled'. Expected boolean, got string
details:
field: enabled
expectedType: boolean
actualType: string
'404':
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Collection not found:
summary: Collection ID not found or not accessible
description: One of the specified collection IDs does not exist or the user does not have access to it.
value:
code: resource_not_found
message: Collection with ID 999 not found or not accessible
details:
resourceType: Collection
resourceId: 999
solution: Verify the collection ID and ensure you have access to it
Target not found:
summary: Target ID not found or not accessible
description: One of the specified target IDs does not exist or the user does not have access to it.
value:
code: resource_not_found
message: Target with ID 999999 not found or not accessible
details:
resourceType: Target
resourceId: 999999
solution: Verify the target ID and ensure it belongs to your organization
Perspective not found:
summary: Perspective ID not found or not accessible
description: One of the specified perspective IDs does not exist or the user does not have access to it.
value:
code: resource_not_found
message: Perspective with ID 99 not found or not accessible
details:
resourceType: Perspective
resourceId: 99
solution: Verify the perspective ID and ensure it is available in your organization
'403':
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 20,\n \"requestCount\": 20,\n \"limits\": [\n {\n \"requestLimit\": 20,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
/public/v1/enterprise-export/scores:
get:
tags:
- Scores - Enterprise Export
summary: Retri
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prewave/refs/heads/main/openapi/prewave-scores-enterprise-export-api-openapi.yml