Skip to main content
Dub

Introduction

Learn how to use Dub's API to programmatically manage resources in your Dub workspace.
3 min read

Dub's API let you manage your Dub resources programmatically.

You can use the API to:

Base URL#

Dub's API is built on REST principles and is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

The Base URL for all API endpoints is:

Terminal

Authentication#

Authentication to Dub's API is performed via the Authorization header with a Bearer token. To authenticate, you need to include the Authorization header with the word Bearer followed by your API key in your requests like so:

Terminal

Here are examples of how to authenticate with Dub's API in different programming languages:

Learn more about how to get your API key.

Native SDKs#

Dub offers native SDKs in some of the most popular programming languages:

You can find the full list of SDKs here.

Error handling#

Dub API returns machine readable error codes, human readable error messages and a link to the docs for more information.

Here is how an error response looks like:

Here is a list of all error codes Dub API returns:

bad_request
  • Status: 400
  • Problem: The request is malformed, either missing required fields, using wrong datatypes, or being syntactically incorrect.
  • Solution: Check the request and make sure it is properly formatted.
unauthorized
  • Status: 401
  • Problem: The request has not been applied because it lacks valid authentication credentials for the target resource.
  • Solution: Make sure you are using the correct API key or access token.
forbidden
  • Status: 403
  • Problem: The server understood the request, but is refusing to fulfill it because the client lacks proper permission.
  • Solution: Make sure you have the necessary permissions to access the resource.
not_found
  • Status: 404
  • Problem: The server has not found anything matching the request URI.
  • Solution: Check the request and make sure the resource exists.
conflict
  • Status: 409
  • Problem: Another resource already uses the same identifier. For example, workspace slug must be unique.
  • Solution: Change the identifier to a unique value.
invite_expired
  • Status: 410
  • Problem: The invite has expired.
  • Solution: Generate a new invite.
unprocessable_entity
  • Status: 422
  • Problem: The server was unable to process the request because it contains invalid data.
  • Solution: Check the request and make sure input data is valid.
rate_limit_exceeded
  • Status: 429
  • Problem: The request has been rate limited.
  • Solution: Wait for a while and try again.
internal_server_error
  • Status: 500
  • Problem: The server encountered an unexpected condition that prevented it from fulfilling the request.
  • Solution: Try again later. If the problem persists, contact support.

Pagination#

Dub's API supports pagination. This is useful when you have a large number of resources and you want to retrieve them in smaller chunks.

These list API methods share a common set of parameters that allow you to control the number of items returned and the page number. For example, you can:

Parameters#

pagestring#

The page number to retrieve. By default, the first page is returned.

Default: "1"

pageSizestring#

The number of items to retrieve per page. The default value varies by endpoint. Maximum value is 100.

sortBystring#

The field to sort the results by.

sortOrderstring#

The order to sort the results by. Can be asc or desc.

Example#

The following example demonstrates how to retrieve the first page of 10 links:

Authentication