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

# API Examples

### Use QStash via:

* cURL
* [Typescript SDK](https://github.com/upstash/sdk-qstash-ts)
* [Python SDK](https://github.com/upstash/qstash-python)

Below are some examples to get you started. You can also check the [how to](/qstash/howto/publishing) section for
more technical details or the [API reference](/qstash/api/messages) to test the API.

### Publish a message to an endpoint

Simple example to [publish](/qstash/howto/publishing) a message to an endpoint.

<Tabs>
  <Tab title="cURL">
    ```shell
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H "Content-type: application/json" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/publish/https://example.com'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    client.publish_json({
      "url": "https://example.com",
      "body": {
        "hello": "world",
      },
    })
    # Async version is also available
    ```
  </Tab>
</Tabs>

### Publish a message to a topic

The [topic](/qstash/features/topics) is a way to publish a message to multiple endpoints in a
fan out pattern.

<Tabs>
  <Tab title="cURL">
    ```shell
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H "Content-type: application/json" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/publish/myTopic'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      topic: "myTopic",
      body: {
        hello: "world",
      },
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    client.publish_json({
      "topic": "myTopic",
      "body": {
        "hello": "world",
      },
    })
    # Async version is also available
    ```
  </Tab>
</Tabs>

### Publish a message with 5 minutes delay

Add a delay to the message to be published. After QStash receives the message,
it will wait for the specified time (5 minutes in this example) before sending the message to the endpoint.

<Tabs>
  <Tab title="cURL">
    ```shell
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H "Content-type: application/json" \
        -H "Upstash-Delay: 5m" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/publish/https://example.com'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
      delay: 300,
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    client.publish_json({
      "url": "https://example.com",
      "body": {
        "hello": "world",
      },
      "delay": 300,
    })
    # Async version is also available
    ```
  </Tab>
</Tabs>

### Send a custom header

Add a custom header to the message to be published.

<Tabs>
  <Tab title="cURL">
    ```shell
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H 'Upstash-Forward-My-Header: my-value' \
        -H "Content-type: application/json" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/publish/https://example.com'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
      headers: {
        "My-Header": "my-value",
      },
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    client.publish_json({
      "url": "https://example.com",
      "body": {
        "hello": "world",
      },
      "headers": {
        "My-Header": "my-value",
      },
    })
    # Async version is also available
    ```
  </Tab>
</Tabs>

### Schedule to run once a day

<Tabs>
  <Tab title="cURL">
    ```shell
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H "Upstash-Cron: 0 0 * * *" \
        -H "Content-type: application/json" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/schedules/https://example.com'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    const schedules = client.schedules();
    await schedules.create({
      destination: "https://example.com",
      cron: "0 0 * * *",
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    schedules = client.schedules()
    schedules.create({
      "destination": "https://example.com",
      "cron": "0 0 * * *",
    })
    # Async version is also available
    ```
  </Tab>
</Tabs>

### Set max retry count to 3

Configure how many times QStash should retry to send the message to the endpoint before
sending it to the [dead letter queue](/qstash/features/dlq).

<Tabs>
  <Tab title="cURL">
    ```shell
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H "Upstash-Retries: 3" \
        -H "Content-type: application/json" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/publish/https://example.com'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
      retries: 3,
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    client.publish_json({
      "url": "https://example.com",
      "body": {
        "hello": "world",
      },
      "retries": 3,
    })
    # Async version is also available
    ```
  </Tab>
</Tabs>

### Set callback url

Receive a response from the endpoint and send it to the specified callback URL.
If the endpoint returns a response, QStash will send it to the failure callback URL.

<Tabs>
  <Tab title="cURL">
    ```shell
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H "Content-type: application/json" \
        -H "Upstash-Callback: https://example.com/callback" \
        -H "Upstash-Failure-Callback: https://example.com/failure" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/publish/https://example.com'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
      callback: "https://example.com/callback",
      failureCallback: "https://example.com/failure",
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    client.publish_json({
      "url": "https://example.com",
      "body": {
        "hello": "world",
      },
      "callback": "https://example.com/callback",
      "failure_callback": "https://example.com/failure",
    })
    # Async version is also available
    ```
  </Tab>
</Tabs>

### List all events

Retrieve a list of all [events](https://upstash.com/docs/qstash/api/events/list) that have
been published.

<Tabs>
  <Tab title="cURL">
    ```shell
    curl https://qstash.upstash.io/v2/events \
        -H "Authorization: Bearer <token>"
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    const events = await client.events()
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    events = client.events()
    # Async version is also available
    ```
  </Tab>
</Tabs>

### List all schedules

<Tabs>
  <Tab title="cURL">
    ```shell
    curl https://qstash.upstash.io/v2/schedules \
        -H "Authorization: Bearer <token>"
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    const schedules = client.schedules();
    const scheds = await schedules.list();
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    client = Client("<QSTASH_TOKEN>")
    schedules = client.schedules()
    scheds = schedules.list()
    # Async version is also available
    ```
  </Tab>
</Tabs>