# Submitting Suggestions

This endpoint lets a coding agent (or developer) report a confirmed gap in Tediware
to the Tediware team: a documented endpoint that answers differently from its docs, a
field or capability you needed that does not exist, or a doc that is wrong. Send one
only after you have checked the docs and tried the documented path. It is not for
reporting your own mistakes, saying thanks, summarizing a task, or passing on general
ideas.

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.

The same submission is available as the `suggestion_submit` [MCP](/resources/api-docs/mcp)
tool, with the same limits. The MCP tool requires `tried` and `expected`.

## Endpoint

```
POST /platform/suggestions
```

Read-only keys cannot submit suggestions.

## Request Body

The request body is JSON with the following fields:

- `body` (required): the gap, meaning what is missing or wrong. Maximum 10,000 characters, including `tried` and `expected`. Do not include document contents, payloads, or customer PII.
- `tried`: what you did, naming the endpoint, tool, or doc you used and what came back. Optional for now; it will become required.
- `expected`: what you expected to find or get instead. Optional for now; it will become required.
- `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.

`tried` and `expected` are stored with the body, under their own headings.

## 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"
}
```

## Repeats and Limits

Send one suggestion per distinct problem, once. You should not expect a reply through
the API.

- **Repeats.** If the same API key sent a suggestion with the same title, or the same
  body, in the last 24 hours, the API returns `200` with that earlier suggestion and
  `"duplicate": true`. No new suggestion is recorded and no second email is sent.
- **Daily cap.** An organization can send 20 suggestions in any 24 hours, across all of
  its keys. Past that, the API returns `429` with `code: "rate_limited"` and
  `reason: "daily_cap"`. Do not retry.
- **Per-minute limit.** Each key can send five a minute, counted across this endpoint and
  the MCP tool together. Past that, the API returns `429` with `code: "rate_limited"` and
  no `reason`.

## 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 mappings doc does not say how repeated line items map for an outbound 850.",
    "tried": "Read /resources/docs/mappings and the 850 implementation schema. Neither names the key that holds the line items.",
    "expected": "An example outbound 850 payload with two line items.",
    "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                           |
| 403    | forbidden         | The key is a read-only key                                  |
| 422    | invalid_parameter | A field failed validation (e.g. unknown category, too long) |
| 429    | rate_limited      | The daily cap (reason: daily_cap) or the per-minute limit   |
```