# Submitting Suggestions

This endpoint lets a coding agent (or developer) send the Tediware team a product
suggestion when it gets stuck: a missing doc, an endpoint that was expected but not
found, a JSON shape that was hard to discover, or any rough edge worth improving.
Each suggestion is recorded and emails the team. It is plain feedback, so nothing is
delivered to a trading partner and there are no control numbers to track.

## Endpoint

```
POST /platform/suggestions
```

## Request Body

The request body is JSON with the following fields:

- `body` (required) -- the suggestion. Describe what is missing or could be better, what you tried, and what you expected. Maximum 10,000 characters. Do not include document contents, payloads, or customer PII.
- `title` (optional) -- a short summary. Maximum 200 characters.
- `category` (optional) -- one of `docs`, `api`, `feature`, or `other`.
- `reference` (optional) -- the doc page, URL, or endpoint the suggestion relates to. Maximum 2,000 characters.
- `traceGuid` (optional) -- the trace identifier of a related processed document, if one is relevant.

## Success Response

On success, the API returns `201` with the created suggestion:

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Outbound 850 line items unclear",
  "category": "docs",
  "status": "new",
  "createdAt": "2026-06-18T14:32:00Z"
}
```

Sending a suggestion is safe to do once: there is nothing to reconcile or retry, and
you should not expect a reply through the API.

## Example Request

```bash
curl -X POST "https://tediware.com/platform/suggestions" \
  -H "Authorization: Key your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Outbound 850 line items unclear",
    "body": "The docs do not explain how repeated line items map for an outbound 850. I expected an array under a lineItems key but could not confirm the shape.",
    "category": "docs",
    "reference": "/resources/docs/mappings"
  }'
```

## Error Responses

```
| Status | Code              | Cause                                                       |
|--------|-------------------|-------------------------------------------------------------|
| 400    | missing_parameter | The body field is missing or blank                          |
| 401    | unauthorized      | The API key is missing or invalid                           |
| 422    | invalid_parameter | A field failed validation (e.g. unknown category, too long) |
| 429    | rate_limited      | Too many suggestions submitted in a short window            |
```