> ## Documentation Index
> Fetch the complete documentation index at: https://dub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Learn how to use Dub's API to programmatically manage resources in your Dub workspace.

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

You can use the API to:

* [Create links](/docs/api-reference/links/create)
* [Create partners](/docs/api-reference/partners/create)
* Track [lead](/docs/api-reference/track/lead) and [sale](/docs/api-reference/track/sale) events
* [Retrieve analytics](/docs/api-reference/analytics/retrieve)

## 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:

```bash Terminal theme={null}
https://api.dub.co
```

## 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](/docs/api-reference/authentication#api-keys) in your requests like so:

```bash Terminal theme={null}
Authorization: Bearer dub_xxxxxx
```

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

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/links \
    --header 'Authorization: Bearer dub_xxxxxx'
  ```

  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  const dub = new Dub({
    token: "dub_xxxxxx",
  });

  // Make API calls
  const links = await dub.links.list();
  ```

  ```python Python theme={null}
  from dub import Dub

  client = Dub(api_key="dub_xxxxxx")

  # Make API calls
  links = client.links.list()
  ```

  ```go Go theme={null}
  import (
    "context"
    "github.com/dubinc/dub-go"
  )

  client := dub.NewClient("dub_xxxxxx")

  // Make API calls
  ctx := context.Background()
  links, err := client.Links.List(ctx)
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  client = Dub::Client.new(api_key: "dub_xxxxxx")

  # Make API calls
  links = client.links.list
  ```

  ```php PHP theme={null}
  use Dub\Client;

  $client = new Client([
      'api_key' => 'dub_xxxxxx'
  ]);

  // Make API calls
  $links = $client->links->list();
  ```
</CodeGroup>

Learn more about [how to get your API key](/docs/api-reference/authentication#api-keys).

## Native SDKs

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

* [TypeScript SDK](/docs/sdks/typescript)
* [Python SDK](/docs/sdks/python)
* [Ruby SDK](/docs/sdks/ruby)
* [PHP SDK](/docs/sdks/php)
* [Go SDK](/docs/sdks/go)

You can find the full list of SDKs [here](/docs/sdks/overview).

## 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:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://dub.co/docs/api-reference/errors#not-found"
  }
}
```

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="invite_expired">
    * **Status:** 410
    * **Problem:** The invite has expired.
    * **Solution:** Generate a new invite.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="rate_limit_exceeded">
    * **Status:** 429
    * **Problem:** The request has been rate limited.
    * **Solution:** Wait for a while and try again.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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:

* [retrieve a list of links](/docs/api-reference/links/list)
* [retrieve a list of domains](/docs/api-reference/domains/create)
* [retrieve a list of events](/docs/api-reference/events/list)

### Parameters

<ParamField body="page" type="string" default="1">
  The page number to retrieve. By default, the first page is returned.
</ParamField>

<ParamField body="pageSize" type="string">
  The number of items to retrieve per page. The default value varies by
  endpoint. Maximum value is 100.
</ParamField>

<ParamField body="sortBy" type="string">
  The field to sort the results by.
</ParamField>

<ParamField body="sortOrder" type="string">
  The order to sort the results by. Can be `asc` or `desc`.
</ParamField>

### Example

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

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/links?page=1&pageSize=10 \
    --header 'Authorization: Bearer <token>'
  ```

  ```javascript Node.js theme={null}
  const res = await dub.links.list({
    page: 1,
    pageSize: 10,
  });
  ```

  ```python Python theme={null}
  res = s.links.list(request={
    "page": 1,
    "page_size": 10,
  })
  ```

  ```go Go theme={null}
  request := operations.GetLinksRequest{
    Page: dubgo.Float64(1),
    PageSize: dubgo.Float64(10),
  }

  ctx := context.Background()
  res, err := s.Links.List(ctx, request)
  ```

  ```ruby Ruby theme={null}
  req = ::OpenApiSDK::Operations::GetLinksRequest.new(
    page: 1,
    page_size: 10,
  )

  res = s.links.list(req)
  ```
</CodeGroup>