Skip to main content

QSTASH API (1.0.0)

Download OpenAPI specification:Download

Documentation of qstash API.

Qstash is a queue system for serverless applications

Endpoints

List

Returns all your existing endpoints.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

Create a new endpoint and susbscribe it to a topic.

Authorizations:
Request Body schema: application/json
topicId
string

The id of the topic this endpoint subscribes to.

Either topicId or topicName must be set

topicName
string

The name of the topic this endpoint subscribes to.

Either topicId or topicName must be set

url
required
string

User controlled service url where we will send webhooks to.

Must not be on local network.

Responses

Request samples

Content type
application/json
{
  • "topicId": "string",
  • "topicName": "string",
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "endpointId": "string",
  • "topicId": "string",
  • "url": "string"
}

Get

Returns all your existing endpoints.

Authorizations:
api_key
path Parameters
endpointId
required
string

The id of the endpoint

Responses

Response samples

Content type
application/json
{
  • "endpointId": "string",
  • "topicId": "string",
  • "url": "string"
}

Update

Update an existing endpoint's url. This will only apply to newly created messages. All messages published before this endpoint was updated will still use the old url.

Authorizations:
api_key
path Parameters
endpointId
required
string
Request Body schema: application/json
url
required
string

The new url of the endpoint

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "endpointId": "string",
  • "topicId": "string",
  • "url": "string"
}

Delete

Deletes an existing endpoint from qstash

Authorizations:
api_key
query Parameters
endpointId
required
string

The id of the endpoint you want to delete.

Responses

Response samples

Content type
application/json
{
  • "error": "Expected type int",
  • "field": "Header: Upstash-Delay"
}

Keys

Get

Get your current and next signing keys.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "current": "string",
  • "next": "string"
}

Rotate

Rotate your signing keys. The next one becomes the current and we generate a new one and assign it to next

Please update the signing keys in your applications as soon as possible.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "current": "string",
  • "next": "string"
}

Messages

List

Returns a list of messages

Authorizations:
api_key
query Parameters
cursor
integer <int64>

Cursor is a unix timestamp with milliseconds precision. You can use it to paginate the results.

Responses

Response samples

Content type
application/json
{
  • "cursor": 0,
  • "messages": [
    ]
}

Get

Get the complete message with the given Id.

Authorizations:
api_key
query Parameters
messageId
required
string

The unique id of the message.

Responses

Response samples

Content type
application/json
{
  • "body": "string",
  • "createdAt": 0,
  • "destinationType": "string",
  • "endpointId": "string",
  • "header": {
    },
  • "messageId": "string",
  • "scheduleId": "string",
  • "settings": {
    },
  • "topicId": "string",
  • "topicName": "string",
  • "url": "string"
}

Cancel

Cancel a message. We will no longer try to deliver this message to any endpoints. All scheduled executions of this message will be canceled as well.

Authorizations:
api_key
query Parameters
messageId
required
string

The unique id of the message you want to cancel

Responses

Response samples

Content type
application/json
{
  • "error": "Expected type int",
  • "field": "Header: Upstash-Delay"
}

Tasks

Returns the last 100 logs in descending chronological order.

Use the cursor parameter to paginate.

Authorizations:
api_key
path Parameters
messageId
required
string

MessageId is the Id of the message to list tasks for.

query Parameters
cursor
integer <int64>

Cursor is a unix timestamp with milliseconds precision. You can use it to paginate the results.

Responses

Response samples

Content type
application/json
{
  • "cursor": 0,
  • "tasks": [
    ]
}

Tasks

Tasks

Returns a list of tasks associated with a message

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "cursor": 0,
  • "tasks": [
    ]
}

Get

Returns information about a task

Authorizations:
api_key
query Parameters
taskId
required
string

Specify the task id for which you want to get information

Responses

Response samples

Content type
application/json
{
  • "completedAt": 0,
  • "deadline": 0,
  • "error": "string",
  • "lastErrorAt": 0,
  • "logs": [
    ],
  • "maxRetry": 0,
  • "messageId": "string",
  • "nextProcessAt": 0,
  • "retried": 0,
  • "state": "string",
  • "taskId": "string",
  • "url": "string"
}

Logs

Returns the last 100 logs in descending chronological order.

Use the cursor parameter to paginate.

Authorizations:
api_key
path Parameters
taskId
required
string

TaskId is the Id of the tasks to list logs for.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Publish

Publish a new message to a topic or directly to a url.

Authorizations:
api_key
path Parameters
Destination
required
string

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://)

header Parameters
Content-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.

For example application/json, application/xml, application/octet-stream, text/plain

Upstash-Deduplication-Id
string
Example: "abcdef"

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.

Upstash-Content-Based-Deduplication
boolean
Example: true

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.

Upstash-Not-Before
integer <int64>
Example: 1657093973

Delay the first delivery attempt until this time

Unix timestamp with second precision.

This overrides Upstash-Delay if both are provided.

Upstash-Delay
string
Example: "50s" | "3m" | "10h" | "1d"

Delay the first delivery attempt.

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.

Upstash-Retries
integer <int64>
Example: 3

How often should this messasge 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.

min(86400, e ** (2 * n))

Upstash-Cron
string
Example: */5 * * * *

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.

Note: it can take up to 60 seconds until the schedule is registered on an available qstash node.

Request Body schema: application/json

The raw request message passed to the endpoints as is

Will be populated from the request body

string <byte>

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "messageId": "string",
  • "scheduleId": "string"
}

Quota

Get your current quota limits.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "maxEndpointsPerTopic": 0,
  • "maxMessageSize": 0,
  • "maxRequestsPerDay": 0,
  • "maxRetries": 0,
  • "maxSchedules": 0,
  • "maxTopics": 0,
  • "retention": 0
}

Schedules

List

Returns a list of schedules

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get

Returns a single schedule

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "createdAt": 0,
  • "cron": "string",
  • "destination": {
    },
  • "scheduleId": "string",
  • "settings": {
    }
}

Delete

Delete a schedule. It can take up to 60s for the schedule to be deleted from the system.

Authorizations:
api_key
query Parameters
scheduleId
required
string

The unique id of the schedule you want to delete

Responses

Response samples

Content type
application/json
{
  • "error": "Expected type int",
  • "field": "Header: Upstash-Delay"
}

Topics

List

Returns all your existing topics.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

Create a new topic in qstash

Authorizations:
api_key
Request Body schema: application/json
name
required
string

The name of the topic Must only contain alphanumeric characters, underscores, dashes and periods. regex: ^[a-zA-Z0-9-_.]+$

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "endpoints": [
    ],
  • "name": "string",
  • "topicId": "string"
}

Get

returns all your existing topics.

Authorizations:
api_key
path Parameters
topic
required
string

The id or name of the topic

Responses

Response samples

Content type
application/json
{
  • "endpoints": [
    ],
  • "name": "string",
  • "topicId": "string"
}

Update

Update an existing topic's name

Authorizations:
api_key
path Parameters
Topic
required
string

Topic name or id

Request Body schema: application/json
name
required
string

The new name of the topic Must only contain alphanumeric characters, underscores, dashes and periods. regex: ^[a-zA-Z0-9-_.]+$

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "endpoints": [
    ],
  • "name": "string",
  • "topicId": "string"
}

Delete

deletes an existing topic from qstash

Authorizations:
api_key
query Parameters
topic
required
string

The name or id for the topic you want to delete.

Responses

Response samples

Content type
application/json
{
  • "error": "Expected type int",
  • "field": "Header: Upstash-Delay"
}