# Recyda API Gateway

> OpenAPI documentation for the Recyda API Gateway.

Production API base URL: https://api-prod.recyda.com
Most endpoints require the `x-recyda-api-client-key` and `x-recyda-api-client-secret` headers.
Each endpoint is rate-limited; exceeding the limit returns 429 Too Many Requests.
Error responses use `{ error: string, status_code: number }`.

## Documentation

- [API Reference](https://api-docs.recyda.com/): Interactive Scalar documentation for the production Recyda API
- [OpenAPI specification](https://api-docs.recyda.com/openapi.yaml): OpenAPI 3.1 document used by this reference

## Packaging Systems

- [POST /v2/import](https://api-prod.recyda.com/v2/import): Imports a single consumer sales unit (packaging system) into Recyda. Validates the body against the ImportInputWrapper JSON Schema. **Rate limit:** 10 requests per second per API client keyed by `x-recyda-api-client-key`.
- [POST /v2/import-many](https://api-prod.recyda.com/v2/import-many): Imports multiple consumer sales units sharing a packaging system group. Validates against ImportManyInputWrapper.
- [POST /v2/evaluate](https://api-prod.recyda.com/v2/evaluate): Imports a packaging system and immediately triggers evaluation. Same input schema as /v2/import.
- [POST /v2/evaluate-many](https://api-prod.recyda.com/v2/evaluate-many): Imports and evaluates multiple packaging systems sharing a group. Same input schema as /v2/import-many.

## Files

- [POST /v2/import-file-records](https://api-prod.recyda.com/v2/import-file-records): Accepts a JSON request body validated against a defined schema. Processes the import of file records into the system. Returns a 204 No Content status on successful import. **Rate limit:** 10 requests per second per API client keyed by `x-recyda-api-client-key`.
- [POST /v2/link-files](https://api-prod.recyda.com/v2/link-files): Creates associations between files and packaging units or components. Accepts a JSON body with reference codes for the file and target entities. Returns a 204 status on success. **Rate limit:** 100 requests per second per API client keyed by `x-recyda-api-client-key`.

## Suppliers

- [POST /v2/import-suppliers](https://api-prod.recyda.com/v2/import-suppliers): Imports an array of suppliers. Returns 204 No Content on success.
- [POST /v2/link-suppliers](https://api-prod.recyda.com/v2/link-suppliers): This endpoint establishes associations between a supplier and specified packaging units and components. It accepts a JSON payload containing a referenceCode, packagingUnitReferenceCodes, and componentReferenceCodes. A successful request returns a 204 status with no content. **Rate limit:** 100 requests per second per API client keyed by `x-recyda-api-client-key`.

## Business Entities

- [POST /v2/import-doc-business-entities](https://api-prod.recyda.com/v2/import-doc-business-entities): Accepts a JSON payload containing business entity details including name, manufacturer and representative information, and a reference code. Validates the request against a predefined schema and returns a 204 status on success. Signatories are managed in the workspace UI and apply to all Declarations of Conformity. **Rate limit:** 10 requests per second per API client keyed by `x-recyda-api-client-key`.
- [POST /v2/link-doc-business-entities](https://api-prod.recyda.com/v2/link-doc-business-entities): Creates associations between business entities and packaging systems. Accepts a JSON array of objects, each with a packagingSystemReferenceCode and up to 50 businessEntityReferenceCodes. Validates against the LinkBusinessEntitiesInput schema and returns a 204 status on success. **Rate limit:** 100 requests per second per API client keyed by `x-recyda-api-client-key`.

## Shipment Volumes

- [POST /v1/import-shipment-volumes](https://api-prod.recyda.com/v1/import-shipment-volumes): Imports shipment volume period data for a single packaging system. Validates against ImportShipmentVolumePeriodsInput.
- [POST /v1/import-many-projects-shipment-volumes](https://api-prod.recyda.com/v1/import-many-projects-shipment-volumes): Imports shipment volume periods for multiple packaging systems. Validates against ImportShipmentVolumePeriodsForMultipleProjects; the object is wrapped in `shipmentVolumeInputs` before forwarding. **Rate limit:** 10 requests per second per API client keyed by `x-recyda-api-client-key`.

## Clients

- [GET /valid_api_client](https://api-prod.recyda.com/valid_api_client): Returns details of the valid API client. The endpoint requires no parameters. A successful response includes client information such as name and permissions. **Rate limit:** 100 requests per minute.

## Evaluation Tasks

- [POST /v2/start-evaluation-task](https://api-prod.recyda.com/v2/start-evaluation-task): Starts an asynchronous evaluation task for the authenticated API client's workspace. Returns the evaluation task ID immediately; task preparation and job dispatch run in the background. **Rate limit:** 1 request per second per API client keyed by `x-recyda-api-client-key`.
- [POST /v2/poll-evaluation-task](https://api-prod.recyda.com/v2/poll-evaluation-task): Returns the current evaluation task status. When includeResults is true, also returns task metadata and paginated evaluation results. **Rate limit:** 1 request per second per API client keyed by `x-recyda-api-client-key`.

## Optional

- [POST /v2/import-group](https://api-prod.recyda.com/v2/import-group): Deprecated. Use `/v2/import-many` instead. Imports a packaging system group using the ImportGroupInputWrapper schema.
- [POST /v2/evaluate-group](https://api-prod.recyda.com/v2/evaluate-group): Deprecated. Use `/v2/evaluate-many` instead. Imports and evaluates a packaging system group. Same input schema as `/v2/import-group`.