---
title: Conventions
description: How paths, filters, retrieves, updates and errors behave across every endpoint.
---

## Paths

Each entity follows the same shape:

| Operation | Request |
| --- | --- |
| List | `GET /entity` |
| Retrieve | `GET /entity/:id` |
| Create | `POST /entity` |
| Update | `PUT /entity/:id` |
| Delete | `DELETE /entity/:id` |

Operations that don't fit this shape, such as `POST /ticket/:ticketId/quote`, have their own paths. The [API reference](/engine-service/public-api/v1/docs/reference) lists all of them.

## Filters

List filters are query parameters. Repeating a parameter builds an array:

```bash
curl "https://next.amfg.ai/engine-service/public-api/v1/model-version?ticketModelId=2001"
curl "https://next.amfg.ai/engine-service/public-api/v1/build-production?ids=1&ids=2"
```

Date filters take a single date, meaning from that date until now, or a range:

```bash
curl "https://next.amfg.ai/engine-service/public-api/v1/project?createdAt=2026-01-01"
curl "https://next.amfg.ai/engine-service/public-api/v1/project?createdAt[from]=2026-01-01&createdAt[to]=2026-07-01"
```

## Retrieves

:::note
A retrieve for a missing id returns `200` with an empty body (`{}` or `[]`), not `404`. Check for an `id` in the response rather than relying on the status code.
:::

## Updates

Updates replace the whole record; they are not patches. Send every field the schema requires, even the ones you are not changing. A missing field returns a `400` that names it.

Deletes can cascade. For example, deleting a machine group also deletes a material whose only group it was.

## Errors

Errors are passed through as the underlying service produced them: the status, `code`, `message` and `type`. A `400` almost always means the request body failed validation, and the message names the field.

```json
400 {"code": 400, "message": "query.ticketModelId is a required field"}
```

Some schemas are strict about types and require a `number` where a copied response field gives you a string (`quotationFormId`, `customerId`, `colorId`, `userId`). The error message tells you which field it is.

Error responses carry two headers, `x-error-source` and `x-error-source-request-id`. Include both in support tickets, because they identify the failing service and request.

## Limits

Every authenticated call is recorded for usage reporting.