> ## Documentation Index
> Fetch the complete documentation index at: https://speakeasy-20cf8bdf.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Data model

> A quick overview of how Dub is structured.

Whether you are using Dub's [API](/api-reference/introduction) or not, this page is a quick way to understand how Dub works.

Within Dub, all data belongs to a [**Workspace**](#workspace). Within a workspace, you have [Links](#links), [Domains](#domains), [Tags](#tags), and more.

## Workspace

[Workspaces](https://dub.co/help/article/what-is-a-workspace) is the defacto way of organizing your links and working with your team on Dub. You can think of a Dub workspace like a workspace on Slack or Discord – it's a shared space where you can [invite your team members](https://dub.co/help/article/how-to-invite-teammates) to collaborate on links.

When interacting with Dub's API, you'll also need to create a [workspace API key](/api-reference/tokens) to authenticate your requests.

<Accordion title="Workspace model">
  <ResponseField name="id" type="string" required>
    The unique ID of the workspace.
  </ResponseField>

  <ResponseField name="name" type="string" required>
    The name of the workspace.
  </ResponseField>

  <ResponseField name="slug" type="string" required>
    The slug of the workspace.
  </ResponseField>

  <ResponseField name="logo" type="string | null" required>
    The logo of the workspace.
  </ResponseField>

  <ResponseField name="usage" type="number" required>
    The usage of the workspace.
  </ResponseField>

  <ResponseField name="usageLimit" type="number" required>
    The usage limit of the workspace.
  </ResponseField>

  <ResponseField name="linksUsage" type="number" required>
    The links usage of the workspace.
  </ResponseField>

  <ResponseField name="linksLimit" type="number" required>
    The links limit of the workspace.
  </ResponseField>

  <ResponseField name="domainsLimit" type="number" required>
    The domains limit of the workspace.
  </ResponseField>

  <ResponseField name="tagsLimit" type="number" required>
    The tags limit of the workspace.
  </ResponseField>

  <ResponseField name="usersLimit" type="number" required>
    The users limit of the workspace.
  </ResponseField>

  <ResponseField name="plan" type="string" required>
    The plan of the workspace.
  </ResponseField>

  <ResponseField name="stripeId" type="string | null" required>
    The Stripe ID of the workspace.
  </ResponseField>

  <ResponseField name="billingCycleStart" type="number" required>
    The date and time when the billing cycle starts for the workspace.
  </ResponseField>

  <ResponseField name="createdAt" type="string" required>
    The date and time when the workspace was created.
  </ResponseField>

  <ResponseField name="users" type="object[]" required>
    The role of the authenticated user in the workspace.

    <Expandable title="properties">
      <ResponseField name="users.role" type="string" required>
        The role of the authenticated user in the workspace.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="domains" type="object[]" required>
    The domains of the workspace.

    <Expandable title="properties">
      <ResponseField name="domains.slug" type="string">
        The domain of the workspace.
      </ResponseField>

      <ResponseField name="domains.primary" type="string">
        Indicates if the domain is the primary domain.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Accordion>

## Links

Links are the bread and butter of Dub. You can shorten any URL to a Dub link, which you can then share with your audience. Links can be [created](/api-reference/endpoint/create-a-new-link), [updated](/api-reference/endpoint/update-a-link), and [deleted](/api-reference/endpoint/delete-a-link) via the [Dub API](/api-reference/introduction) or the [Dub dashboard](https://app.dub.co).

<Accordion title="Link model">
  <ResponseField name="id" type="string" required>
    The unique ID of the short link. Prefixed with `link_`.
  </ResponseField>

  <ResponseField name="domain" type="string" required>
    The domain of the short link. If not provided, the primary domain for the
    workspace will be used (or dub.sh if the workspace has no domains).
  </ResponseField>

  <ResponseField name="key" type="string" required>
    The short link slug. If not provided, a random 7-character slug will be
    generated.
  </ResponseField>

  <ResponseField name="url" type="string" required>
    The destination URL of the short link.
  </ResponseField>

  <ResponseField name="shortLink" type="string" required>
    The full URL of the short link, including the https protocol (e.g.
    `https://d.to/try`).
  </ResponseField>

  <ResponseField name="trackConversion" type="boolean" default="false">
    Whether to track conversions for the short link.
  </ResponseField>

  <ResponseField name="externalId" type="string | null">
    The ID of the link in your database. If set, it can be used to identify the
    link in future API requests (must be prefixed with `ext_` when passed as a
    query parameter). This key is unique across your workspace.
  </ResponseField>

  <ResponseField name="tenantId" type="string | null">
    The ID of the tenant that created the link inside your system. If set, it can
    be used to fetch all links for a tenant.
  </ResponseField>

  <ResponseField name="archived" type="boolean" required default="false">
    Whether the short link is archived.
  </ResponseField>

  <ResponseField name="expiresAt" type="string | null">
    The date and time when the short link will expire in ISO-8601 format.
  </ResponseField>

  <ResponseField name="expiredUrl" type="string | null">
    The URL to redirect to when the short link has expired.
  </ResponseField>

  <ResponseField name="password" type="string | null">
    The password required to access the destination URL of the short link.
  </ResponseField>

  <ResponseField name="proxy" type="boolean" required default="false">
    Whether the short link uses Custom Social Media Cards feature.
  </ResponseField>

  <ResponseField name="title" type="string | null">
    The title of the short link generated via api.dub.co/metatags. Will be used
    for Custom Social Media Cards if proxy is true.
  </ResponseField>

  <ResponseField name="description" type="string | null">
    The description of the short link generated via api.dub.co/metatags. Will be
    used for Custom Social Media Cards if proxy is true.
  </ResponseField>

  <ResponseField name="image" type="string | null">
    The image of the short link generated via api.dub.co/metatags. Will be used
    for Custom Social Media Cards if proxy is true.
  </ResponseField>

  <ResponseField name="video" type="string | null">
    The custom link preview video (og:video). Will be used for Custom Social Media
    Cards if `proxy` is true. Learn more: [https://d.to/og](https://d.to/og)
  </ResponseField>

  <ResponseField name="rewrite" type="boolean" required default="false">
    Whether the short link uses link cloaking.
  </ResponseField>

  <ResponseField name="doIndex" type="boolean" required default="false">
    Whether to allow search engines to index the short link.
  </ResponseField>

  <ResponseField name="ios" type="string | null">
    The iOS destination URL for the short link for iOS device targeting.
  </ResponseField>

  <ResponseField name="android" type="string | null">
    The Android destination URL for the short link for Android device targeting.
  </ResponseField>

  <ResponseField name="publicStats" type="boolean" required default="false">
    Whether the short link's stats are publicly accessible.
  </ResponseField>

  <ResponseField name="tags" type="object[] | null">
    The tags assigned to the short link.

    <Expandable title="properties">
      <ResponseField name="tags.id" type="string">
        The unique ID of the tag.
      </ResponseField>

      <ResponseField name="tags.name" type="string">
        The name of the tag.
      </ResponseField>

      <ResponseField name="tags.color" type="string">
        The color of the tag.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="webhookIds" type="string[]">
    The IDs of the webhooks that the short link is associated with.
  </ResponseField>

  <ResponseField name="comments" type="string | null">
    The comments for the short link.
  </ResponseField>

  <ResponseField name="qrCode" type="string">
    The full URL of the QR code for the short link (e.g.
    `https://api.dub.co/qr?url=https://d.to/try`).
  </ResponseField>

  <ResponseField name="utm_source" type="string | null">
    The UTM source of the short link.
  </ResponseField>

  <ResponseField name="utm_medium" type="string | null">
    The UTM medium of the short link.
  </ResponseField>

  <ResponseField name="utm_campaign" type="string | null">
    The UTM campaign of the short link.
  </ResponseField>

  <ResponseField name="utm_term" type="string | null">
    The UTM term of the short link.
  </ResponseField>

  <ResponseField name="utm_content" type="string | null">
    The UTM content of the short link.
  </ResponseField>

  <ResponseField name="userId" type="string">
    The user ID of the creator of the short link.
  </ResponseField>

  <ResponseField name="workspaceId" type="string">
    The workspace ID of the short link.
  </ResponseField>

  <ResponseField name="clicks" type="number" required default="0">
    The number of clicks on the short link.
  </ResponseField>

  <ResponseField name="leads" type="number" required default="0">
    The number of leads the short link has generated.
  </ResponseField>

  <ResponseField name="sales" type="number" required default="0">
    The number of sales the short link has generated.
  </ResponseField>

  <ResponseField name="saleAmount" type="number" required default="0">
    The total dollar amount of sales the short link has generated (in cents).
  </ResponseField>

  <ResponseField name="lastClicked" type="string | null">
    The date and time when the short link was last clicked.
  </ResponseField>

  <ResponseField name="createdAt" type="string">
    The date and time when the short link was created.
  </ResponseField>

  <ResponseField name="updatedAt" type="string">
    The date and time when the short link was last updated.
  </ResponseField>

  <ResponseField name="programId" type="string | null">
    The ID of the program the short link is associated with.
  </ResponseField>
</Accordion>

## Domains

On Dub, you can [add custom domains](https://dub.co/help/article/how-to-add-custom-domain) to create branded short links for better brand recognition. You can also [set a primary domain](https://dub.co/help/article/how-to-set-primary-domain) for it to be used as the default domain for new links (both via the API and the dashboard).

<Accordion title="Domain model">
  <ResponseField name="id" type="string" required>
    The unique identifier of the domain.
  </ResponseField>

  <ResponseField name="slug" type="string" required>
    The domain name.
  </ResponseField>

  <ResponseField name="verified" type="boolean" default={false} required>
    Whether the domain is verified.
  </ResponseField>

  <ResponseField name="primary" type="boolean" default={false} required>
    Whether the domain is the primary domain for the workspace.
  </ResponseField>

  <ResponseField name="archived" type="boolean" default={false} required>
    Whether the domain is archived.
  </ResponseField>

  <ResponseField name="placeholder" type="string" default="https://dub.co/help/article/what-is-dub" required>
    Provide context to your teammates in the link creation modal by showing them
    an example of a link to be shortened.
  </ResponseField>

  <ResponseField name="expiredUrl" type="string | null" required>
    The URL to redirect to when a link under this domain has expired.
  </ResponseField>

  <ResponseField name="notFoundUrl" type="string | null" required>
    The URL to redirect to when a link under this domain doesn't exist.
  </ResponseField>

  <ResponseField name="createdAt" type="string" required>
    The date the domain was created.
  </ResponseField>

  <ResponseField name="updatedAt" type="string" required>
    The date the domain was last updated.
  </ResponseField>

  <ResponseField name="registeredDomain" type="object | null" required>
    The registered domain record.

    <Expandable title="properties">
      <ResponseField name="id" type="string" required>
        The ID of the registered domain record.
      </ResponseField>

      <ResponseField name="createdAt" type="string" required>
        The date the domain was created.
      </ResponseField>

      <ResponseField name="expiresAt" type="string" required>
        The date the domain expires.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Accordion>

## Tags

Tags are a way to organize your links. You can [add tags to your links](https://dub.co/help/article/how-to-use-tags) to categorize them and make them easier to find. You can also [filter analytics by tags](https://dub.co/blog/introducing-tags#filtering-analytics-by-tags) to get a better understanding of how your campaigns are performing.

<Accordion title="Tag model">
  <ResponseField name="id" type="string" required>
    The unique ID of the tag.
  </ResponseField>

  <ResponseField name="name" type="string" required>
    The name of the tag.
  </ResponseField>

  <ResponseField name="color" type="string" required>
    The color of the tag.
  </ResponseField>
</Accordion>