API Examples

Use QStash via:

• cURL
• Typescript SDK
• Python SDK

Below are some examples to get you started. You can also check the how to section for more technical details or the API reference to test the API.

Publish a message to an endpoint

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

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

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

Publish a message to a topic

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/myTopic'

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/myTopic'

const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
  topic: "myTopic",
  body: {
    hello: "world",
  },
});

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "topic": "myTopic",
  "body": {
    "hello": "world",
  },
})
# Async version is also available

Publish a message with 5 minutes delay

• cURL
• Typescript SDK
• Python SDK

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'

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'

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

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

Send a custom header

• cURL
• Typescript SDK
• Python SDK

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'

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'

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

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

Schedule to run once a day

• cURL
• Typescript SDK
• Python SDK

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'

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'

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

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

Set max retry count to 3

• cURL
• Typescript SDK
• Python SDK

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'

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'

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

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

Set callback url

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -H "Upstash-Callback: https://example.com/callback" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -H "Upstash-Callback: https://example.com/callback" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

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

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "url": "https://example.com",
  "body": {
    "hello": "world",
  },
  "callback": "https://example.com/callback",
})
# Async version is also available

List all events

• cURL
• Typescript SDK
• Python SDK

curl https://qstash.upstash.io/v2/events \
    -H "Authorization: Bearer <token>"

curl https://qstash.upstash.io/v2/events \
    -H "Authorization: Bearer <token>"

const client = new Client({ token: "<QSTASH_TOKEN>" });
const events = await client.events()

client = Client("<QSTASH_TOKEN>")
events = client.events()
# Async version is also available

List all schedules

• cURL
• Typescript SDK
• Python SDK

curl https://qstash.upstash.io/v2/schedules \
    -H "Authorization: Bearer <token>"

curl https://qstash.upstash.io/v2/schedules \
    -H "Authorization: Bearer <token>"

const client = new Client({ token: "<QSTASH_TOKEN>" });
const schedules = client.schedules();
const scheds = await schedules.list();

client = Client("<QSTASH_TOKEN>")
schedules = client.schedules()
scheds = schedules.list()
# Async version is also available