# AmunCore REST API reference

> Every AmunCore endpoint is a REST URL under /api/v1/{appId}/{endpointName}, protected by an API key, with paging, sorting, column filters and a consistent JSON response and error format.

## Authentication

Send the application's API key with every request, in either header:

```
X-Api-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
```

Scoped keys can be read-only, write-only or full access, with an expiry date. See [Security and access control](https://amuncore.com/docs/security.md).

## Operations

| Method | URL | What it does |
|---|---|---|
| GET | /api/v1/{appId}/{endpointName} | List records |
| GET | /api/v1/{appId}/{endpointName}/{id} | Get one record |
| POST | /api/v1/{appId}/{endpointName} | Create a record |
| PUT | /api/v1/{appId}/{endpointName}/{id} | Update a record |
| DELETE | /api/v1/{appId}/{endpointName}/{id} | Delete a record |

Each method works only when the endpoint allows it.

## Filtering, paging and sorting

```
GET /api/v1/shop/customers?Status=active&City=Cairo
GET /api/v1/shop/customers?page=2&pageSize=50&orderBy=Name&orderDir=asc
```

- Column filters: `?ColumnName=value`.
- Paging: `page` and `pageSize`.
- Sorting: `orderBy` and `orderDir` (`asc` or `desc`).

Paging starts when `page` is sent: `pageSize` is 20 by default and at most 500. Without `page`, every record you may see is returned.

## Responses

Reads:

```json
{ "success": true, "data": [ { "Id": 1, "Name": "Acme Co" } ], "meta": { "endpoint": "customers", "method": "GET", "durationMs": 9, "timestamp": "2026-10-27T10:30:00Z" } }
```

Writes return the record as the database wrote it (POST answers 201):

```json
{ "success": true, "data": { "Id": 43, "Name": "Nile Foods" }, "meta": { "endpoint": "customers", "method": "POST", "durationMs": 18, "timestamp": "2026-10-27T10:30:00Z" } }
```

## Writing safely

- **Idempotency-Key**: send `Idempotency-Key: <a UUID>` with POST, PUT or DELETE. A retry with the same key and body returns the first answer (`"idempotentReplay": true`, header `Idempotency-Replayed: true`) and writes nothing. The same key with a different body answers 409. Keys are kept 24 hours.
- **Dry run**: add `?dryRun=true` (or `X-Dry-Run: true`) to check a write without doing it. Every check runs; a change or delete says how many records it would touch; nothing is written, held for approval or sent to webhooks. Not available for stored procedures or external APIs (400).
- **Approval**: an endpoint with an approval policy answers 202 with `approvalRequestId`; nothing is saved until an approver accepts it.
- **Undoing**: a created record can be removed with DELETE; a change can be undone with a PUT of the previous values (read them first). A DELETE cannot be undone: AmunCore keeps no copy of your records.

```json
{ "success": true, "data": { "dryRun": true, "action": "update", "fields": ["City"], "id": "42", "matches": 1,
  "message": "Checked: 1 record would be updated. Nothing was saved.", "approvalNeeded": false } }
```

## Errors

Every error has the same JSON shape: `success` (false), `message` (readable), and where relevant `error` (a short code), `requestId` and `timestamp`.

| Status | Meaning |
|---|---|
| 400 | Bad request |
| 401 | Missing or invalid API key |
| 403 | The key may not do this (read-only key, IP allow list) |
| 404 | Not found |
| 405 | The endpoint answers another method |
| 409 | Idempotency-Key used with a different body, or the same request still running |
| 422 | An endpoint that answers with a Shape: the document did not pass its checks |
| 429 | Too many calls (the plan's allowance, or the endpoint's calls per minute); see Retry-After |
| 500 | Server error |

A change sent to an endpoint with an approval policy is held for approval instead of being saved straight away.

## GraphQL-style queries

Fetch several endpoints and choose exact fields in one request:

```
POST /graphql/{appId}
X-Api-Key: YOUR_API_KEY

{ "queries": [
  { "endpoint": "customers", "fields": ["Id","Name","Email"], "limit": 10 },
  { "endpoint": "orders", "fields": ["Id","Total","Status"], "limit": 5 }
] }
```

Only fields the endpoint exposes can be asked for.

## Webhooks

AmunCore can POST to your URL when records are created, updated or deleted, with timeouts, retries and custom headers. Each delivery carries:

- `X-AmunCore-Signature`: HMAC-SHA256 of the body, to verify it came from AmunCore.
- `X-AmunCore-Delivery`: a unique delivery id, to ignore duplicate retries.
- `X-AmunCore-Attempt`: the attempt number.

## Limits

Every answer of a plan with a call allowance carries `X-RateLimit-Limit` (the plan's calls) and `X-RateLimit-Remaining` (calls left). An endpoint can also allow only so many calls a minute. Either limit answers 429 with `Retry-After`.

## Versions and status

The API is versioned in its path (`/api/v1`). Every release is in the [changelog](https://amuncore.com/docs/changelog.md). [Service status](https://amuncore.com/status).

## OpenAPI

- [OpenAPI 3.0 specification](https://amuncore.com/openapi.json) (public), with examples and code samples for every operation
- [Swagger UI](https://amuncore.com/swagger)

Each application also gets generated, shareable documentation for its own endpoints, with code samples in cURL, JavaScript, Python, C# and PHP.

Back to the [AmunCore overview](https://amuncore.com/llms.txt).
