---
title: Submit a source recommendation
description: Optional idempotency key.
---
# Submit a source recommendation

`POST https://api.releases.sh/v1/recommendations`

Optional idempotency key. Reuse the same key only for an identical request; successful responses are replayable for 24 hours.

**Auth:** optional Bearer token.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Optional idempotency key. Reuse the same key only for an identical request; successful responses are replayable for 24 hours. |

**Request body** (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | "source" | yes |  |
| `url` | string | yes | http(s) URL of the changelog or project. |
| `note` | string | no |  |
| `contactEmail` | string | no |  |
| `surface` | string | no |  |

**Responses**

- `202` Accepted recommendation identifier.
- `400` Invalid type, URL, or contact email
- `409` The key is already processing, or was reused with a different request fingerprint.
- `429` Rate limited
- `503` Recommendation intake disabled (kill switch), or idempotency storage/response replay is temporarily unavailable

Full request and response schemas: [OpenAPI 3.1 spec](https://api.releases.sh/v1/openapi.json).