> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-vector.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish Message

> This endpoint publishes a new message to a topic or directly to a url 

## Request

<ParamField path="destination" type="string" required>
  Destination can either be a topic name or id that you configured in the
  Upstash console, or a valid url where the message gets sent to. Make sure the
  url is prefixed with a valid protocol (`http://` or `https://`)
</ParamField>

<ParamField body="body" type="string">
  The raw request message passed to the endpoints as is
</ParamField>

<ParamField header="Content-Type" type="string">
  ContentType is the MIME type of the message.

  We highly recommend sending a `Content-Type` header along, as this will help
  your destination API to understand the content of the message.

  Example: `application/json`, `application/xml`, `application/octet-stream`,
  `text/plain`
</ParamField>

<ParamField header="Upstash-Deduplication-Id" type="string">
  Provide a unique id for deduplication.

  This id will be used to detect duplicate messages. If a duplicate message is detected, the request will be accepted but not enqueued. Deduplication ids must not contain : or whitespace.

  We store deduplication ids for 90 days. Afterwards it is possible that the message with the same deduplication id is delivered again.

  When scheduling a message, the deduplication happens before the schedule is created.
</ParamField>

<ParamField header="Upstash-Content-Based-Deduplication" type="boolean">
  If true, the message content will get hashed and used as deduplication id. If a duplicate message is detected, the request will be accepted but not enqueued.

  The content based hash includes the following values:

  * All headers prefixed with Upstash this includes all custom headers you are sending.

  * The entire raw request body

  * The destination from the url path

  We store deduplication ids for 90 days. Afterwards it is possible that the message with the same deduplication id is delivered again.

  When scheduling a message, the deduplication happens before the schedule is created. Messages created by schedules are not deduplicated.
</ParamField>

<ParamField header="Upstash-Not-Before" type="int">
  Delay the first delivery attempt until this time

  Unix timestamp with second precision.

  This overrides `Upstash-Delay` if both are provided.
</ParamField>

<ParamField header="Upstash-Method" type="string">
  The HTTP method to use when sending a webhook to your API.
</ParamField>

<ParamField header="Upstash-Delay" type="string">
  Delay the message delivery.

  Format for this header is a number followed by duration abbreviation, like
  `10s`. Available durations are `s` (seconds), `m` (minutes), `h` (hours), `d`
  (days).

  Overridden by `Upstash-Not-Before` if both are provided.

  Example: `"50s" | "3m" | "10h" | "1d"`
</ParamField>

<ParamField header="Upstash-Retries" type="int">
  How often should this message be retried in case the destination API is not available.

  The total number of deliveries is therefore capped at `1 + retries`

  Leave this empty to use the default value, (free tier: 3, paid tier: 5)

  The backoff duration in seconds is calculated as follows: `n` is the number of
  times the task has been retried.

  Example: `min(86400, e ** (2 * n))`
</ParamField>

<ParamField header="Upstash-Cron" type="string">
  Cron allows you to send this message periodically on a schedule.

  Add a Cron expression and we will requeue this message automatically whenever the Cron expression triggers. We offer an easy to use UI for creating Cron expressions in our console or you can check out [Crontab.guru](https://crontab.guru).

  Example: `"*/5 * * * *"`

  <Note>
    It can take up to 60 seconds until the schedule is registered on an available QStash node.
  </Note>
</ParamField>

<ParamField header="Upstash-Callback" type="string">
  You can define a callback url that will be called with the response from the destination API.

  Callbacks are experimental, and the API might change in the future!

  The callback url must be prefixed with a valid protocol (`http://` or `https://`) Callbacks are charged as a regular message. Callbacks will use the retry setting from the original request.
</ParamField>

<ParamField header="Upstash-Forward-*" type="string">
  You can send custom headers along with your message.

  To send a custom header, prefix the header name with `Upstash-Forward-`. We will strip efix and them to the destination API.

  Example: `"Upstash-Forward-My-Header: my-value"` -> `"My-Header: my-value"`
</ParamField>

## Response

### Response Header

<ResponseField name="Upstash-Deduplication-Id" type="string">
  Provide a unique id for deduplication.

  This id will be used to detect duplicate messages. If a duplicate message is detected, the request will be accepted but not enqueued. Deduplication ids must not contain `:` or whitespace.

  We store deduplication ids for 90 days. Afterwards it is possible that the message with the same deduplication id is delivered again.

  When scheduling a message, the deduplication happens before the schedule is created.
</ResponseField>

### Response Body

<ResponseField name="messageId" type="string" required>
  A unique of the message

  Only set when you publish a message without Cron schedule.
</ResponseField>

<ResponseField name="scheduleId" type="string" required>
  The unique id of this schedule. You can use it to delete the schedule later.
</ResponseField>

<RequestExample>
  ```sh
  curl -X POST "https://qstash.upstash.io/v1/publish/https://www.example.com" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -H "Upstash-Deduplication-Id: unique123" \
    -H "Upstash-Content-Based-Deduplication: true" \
    -H "Upstash-Not-Before: 1691245856" \
    -H "Upstash-Method: POST" \
    -H "Upstash-Delay: 10s" \
    -H "Upstash-Retries: 3" \
    -H "Upstash-Forward-Custom-Header: custom-value" \
    -d '{"message":"Hello, World!"}'
  ```
</RequestExample>

<ResponseExample>
  ```json url
  {
    "messageId": "msg_abc123"
  }
  ```

  ```json topic
  {
    "messageId": "msg_abc123"
  }
  ```

  ```json schedule
  {
    "scheduleId": "scd_def456"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 202 Duplicate Request
  {"Upstash-Deduplication-Id: unique123"}
  ```
</ResponseExample>