API Referenceurl-api

DyLy Link API

DyLy Link API

Version
v1
Server
https://dyly-api.lilacwells.dev/api/v1

links

post/links

create links

#create-short-urls

Creates a DyLy short link belonging to the authenticated project.

Supported link types

  • url: Redirects the visitor to destinationUrl.
  • json: Returns the JSON payload stored in rawJson.
  • jwt: Returns a signed JWT built from jwtClaims. When destinationUrl is supplied the JWT is delivered via the redirect target; otherwise it is returned inline. Implicit flow appends the token to the fragment, while code flow issues a one-time authorization code.
  • deep: Issues a deep link with a signed token query string for downstream validation. If the app is not installed the user is redirected to destinationUrl.

Validation and defaults

  • projectId must belong to the caller. Authorization failures return 401 or 403.
  • domain is normalized to lowercase and must be registered for the project. When omitted the project's default domain is used.
  • TTL (expiresIn) defaults to unlimited access when capabilities allow. If the project cannot control TTL, the service forces a 24 hour TTL. A positive TTL must be at least 60 seconds.
  • For jwt links jwtClaims are required. Providing a destinationUrl also requires flow; setting flow: code additionally requires clientType. A secure code verifier is generated automatically for code flow.
  • For json links rawJson must contain a valid payload within platform limits (depth ≤ 4, arrays ≤ 10 items, string length ≤ 192 characters).
  • For url and deep links destinationUrl must be an absolute http(s) URL.
  • oneTime and keyProtected require the corresponding project capability. If the project lacks the capability the value is coerced to false. When keyProtected is enabled the returned shortUrl contains a key query string parameter.
  • Custom path values must match the documented pattern. When omitted a unique path is generated.

Response

  • Returns the persisted link metadata including the generated alias and, for JWT code flow, the server-issued codeVerifier.

Rate limiting & quotas

  • Project rate limits and link quotas are evaluated for every request. Exceeding the limits results in 429 or 403 responses depending on the violation.

Parameters

Authorizationheaderrequired

HTTP Basic authentication using the DyLy client credentials. Format: Authorization: Basic base64(clientId:clientSecret) for a client that can access the target project.

string

Request body

Required · application/json

object

  • projectIdrequiredstring / uuid

    GUID of the project that owns the link. Must match the authenticated project context and must be a valid UUID v4 format.

  • typerequiredstring

    Link type to create. Supported values: url, json, jwt, or deep. Each type drives validation and how the link behaves when accessed.

  • domainstring

    Domain that will host the link (e.g., myproject.dyly.dev). Must be lowercase and registered to the project. If omitted, the project's default domain is used.

  • destinationUrlstring

    Absolute HTTP(S) URL to redirect to. Required for url and deep links, optional for jwt links. When provided for jwt, you must also set flow.

  • pathstring

    Optional custom path (1–3 segments of lowercase letters, digits, -, or .). Each segment can be 1-36 characters. The service generates a unique path when omitted. Reserved paths such as .well-known/jwks.json, state-validation, and deferred-params are rejected.

  • rawJsonobject

    JSON payload returned when the link is accessed. Required for json links. Payloads must satisfy platform limits (nesting depth ≤ 4, arrays ≤ 10 items, string length ≤ 192 characters).

  • jwtClaimsobject

    Claims to include in JWT responses. Required for jwt links and optional for deep links. Reserved top-level claims (iss, iat, exp, nbf, jti, path, queryString, fragment) are populated by the service and must not be supplied.

  • jwtExpiresInnumber

    Lifetime of the issued JWT in seconds. Accepts values between 300 (5 minutes) and 86,400 (24 hours). Defaults to 900 (15 minutes).

  • expiresInnumber

    Lifetime of the link in seconds. 0 (default) keeps the link active indefinitely when allowed. Positive values below 60 are rejected. If the project cannot manage TTL, the service coerces the value to 86,400 seconds (24 hours). Maximum is 31,536,000 seconds (1 year).

  • oneTimeboolean

    When true, the link can be used only once. Requires the one-time-link capability (Standard Plan); otherwise the value is forced to false.

  • keyProtectedboolean

    When true, the link requires an opaque key query parameter for access. Requires the protected-link capability (Standard Plan); otherwise the value is forced to false. If enabled, the response includes the generated key in shortUrl.

  • flowstring

    JWT retrieval flow when type is jwt and destinationUrl is specified. Use implicit to append the token to the URL fragment, or code to issue a one-time authorization code with PKCE support.

  • clientTypestring

    Required when flow is code. Indicates whether the link was created for a public or confidential client, which controls PKCE requirements. Public clients must provide a code verifier, while confidential clients use a client secret.

Responses

200application/json

Link created successfully. Returns the complete link metadata including the generated short URL and alias.

object

  • projectIdstring / uuid

    Project UUID (v4) that owns the link.

  • destinationUrlstring

    Redirect target URL returned when the link is accessed. Present for url, deep, and redirect-style jwt links. Null for json and inline jwt links.

  • pathstring

    Relative path assigned to the link (without domain). Auto-generated as a unique identifier unless a custom path was supplied during creation.

  • rawJsonobject

    JSON payload returned to callers for json links. Omitted for other link types. The payload adheres to platform limits (nesting depth ≤ 4, arrays ≤ 10 items, string length ≤ 192 characters, key length ≤ 32 characters).

  • jwtClaimsobject

    Claims stored for JWT-based links (jwt or deep type). Reserved top-level claims (iss, iat, exp, nbf, jti, path, queryString, fragment) are populated automatically by the platform and not included here.

  • shortUrlstring

    Fully-qualified URL that end users visit to access the link. Includes the generated key query parameter when keyProtected is true (e.g., https://myproject.dyly.dev/my-custom-path?key=abc123).

  • aliasstring

    The unique identifier for the link (base64-encoded). Use this value with lookup, update, and deletion APIs. Length: 1-1024 characters.

  • expiresInnumber

    Remaining lifetime in seconds before the link expires and becomes inaccessible. null or 0 indicates the link does not expire automatically.

  • jwtExpiresInnumber

    Lifetime in seconds for JWT tokens produced by the link (between 300 and 86,400 seconds). Only populated for jwt and deep links.

  • createdAtstring / date-time

    ISO 8601 timestamp indicating when the link was created.

  • oneTimeboolean

    Indicates whether the link can be consumed only once. After the first access, the link becomes invalid.

  • typestring

    Link type stored for the resource. Possible values: url (simple redirect), json (returns JSON payload), jwt (issues signed token), or deep (app deep link with token).

  • keyProtectedboolean

    True when the link requires a key query parameter for access. The key value is included in shortUrl when this is enabled.

  • flowstring

    JWT retrieval flow when the link was created with a redirect (implicit appends token to fragment, code issues authorization code). Only present for jwt links with destinationUrl.

  • domainstring

    Fully qualified domain name hosting the link.

  • codeVerifierstring

    PKCE code verifier generated for JWT code flow links. Returned during creation so public clients can exchange the authorization code. Only present for jwt links with flow: code.

  • clientTypestring

    Client classification associated with the link (public or confidential). Present for JWT code flow links and determines the authentication requirements.

400application/json

Invalid request. Validation failed for one or more parameters, or business rules were violated (e.g., missing required fields for link type, invalid URL format, reserved path used).

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

401application/json

Unauthorized. The Authorization header is missing, malformed, or contains invalid credentials.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

403application/json

Forbidden. The authenticated client does not have permission to create links for the specified project, or quota/rate limits have been exceeded.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Not found. The specified project or domain does not exist.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

429application/json

Too many requests. Rate limit exceeded for the current user or project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

get/links

Retrieves paginated short links for the specified domain within the authenticated project.

  • domain must belong to the project.
  • maxItemCount defaults to 100 items and higher values are clipped to that maximum.
  • continuationToken should be the string value returned by the previous page. Omit it to receive the first page.

Parameters

domainqueryrequired

Fully qualified domain name that owns the links to return (e.g., myproject.dyly.dev). Must be registered to the authenticated project. The domain is normalized to lowercase.

string

maxItemCountquery

Maximum number of links to return per page. Defaults to 100 and must be between 1 and 100. Values above 100 are coerced to 100.

integer

continuationTokenquery

Opaque continuation token returned by a previous list-short-urls response. Use this to retrieve the next page of results. Omit this parameter to retrieve the first page.

string

Authorizationheaderrequired

HTTP Basic credentials (Basic base64(clientId:clientSecret)) for a client that can read links for the supplied domain.

string

Responses

200application/json

Links retrieved successfully. Returns a paginated list of links for the specified domain.

object

  • projectIdstring / uuid

    Project UUID (v4) for the domain queried.

  • continuationTokenstring

    Opaque continuation token to request the next page of results. Omitted on the final page when no more results are available.

  • linksarray

    Collection of short links that matched the request, ordered by creation time (newest first). Each item follows the urlResponse schema.

    array

    Collection of short links that matched the request, ordered by creation time (newest first). Each item follows the urlResponse schema.

    Items

    object

    • projectIdstring / uuid

      Project UUID (v4) that owns the link.

    • destinationUrlstring

      Redirect target URL returned when the link is accessed. Present for url, deep, and redirect-style jwt links. Null for json and inline jwt links.

    • pathstring

      Relative path assigned to the link (without domain). Auto-generated as a unique identifier unless a custom path was supplied during creation.

    • rawJsonobject

      JSON payload returned to callers for json links. Omitted for other link types. The payload adheres to platform limits (nesting depth ≤ 4, arrays ≤ 10 items, string length ≤ 192 characters, key length ≤ 32 characters).

    • jwtClaimsobject

      Claims stored for JWT-based links (jwt or deep type). Reserved top-level claims (iss, iat, exp, nbf, jti, path, queryString, fragment) are populated automatically by the platform and not included here.

    • shortUrlstring

      Fully-qualified URL that end users visit to access the link. Includes the generated key query parameter when keyProtected is true (e.g., https://myproject.dyly.dev/my-custom-path?key=abc123).

    • aliasstring

      The unique identifier for the link (base64-encoded). Use this value with lookup, update, and deletion APIs. Length: 1-1024 characters.

    • expiresInnumber

      Remaining lifetime in seconds before the link expires and becomes inaccessible. null or 0 indicates the link does not expire automatically.

    • jwtExpiresInnumber

      Lifetime in seconds for JWT tokens produced by the link (between 300 and 86,400 seconds). Only populated for jwt and deep links.

    • createdAtstring / date-time

      ISO 8601 timestamp indicating when the link was created.

    • oneTimeboolean

      Indicates whether the link can be consumed only once. After the first access, the link becomes invalid.

    • typestring

      Link type stored for the resource. Possible values: url (simple redirect), json (returns JSON payload), jwt (issues signed token), or deep (app deep link with token).

    • keyProtectedboolean

      True when the link requires a key query parameter for access. The key value is included in shortUrl when this is enabled.

    • flowstring

      JWT retrieval flow when the link was created with a redirect (implicit appends token to fragment, code issues authorization code). Only present for jwt links with destinationUrl.

    • domainstring

      Fully qualified domain name hosting the link.

    • codeVerifierstring

      PKCE code verifier generated for JWT code flow links. Returned during creation so public clients can exchange the authorization code. Only present for jwt links with flow: code.

    • clientTypestring

      Client classification associated with the link (public or confidential). Present for JWT code flow links and determines the authentication requirements.

400application/json

Invalid request. The domain parameter does not match the required format or other validation failed.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

401application/json

Unauthorized. The Authorization header is missing, malformed, or contains invalid credentials.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

403application/json

Forbidden. The authenticated client does not have permission to list links for the specified domain or rate limit exceeded.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Not found. The specified domain does not exist or is not registered to the authenticated project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

429application/json

Too many requests. Rate limit exceeded for the current user or project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

delete/links/{alias}

Permanently deletes a short link and any stored sessions tied to the alias. The operation is idempotent for authorized callers.

  • The alias is the string returned when the link was created.
  • Deleting a link prevents future redirects.

Parameters

aliaspathrequired

The unique identifier (alias) of the link to delete. This is the base64-encoded value returned when the link was created. Accepts alphanumeric characters, hyphens, underscores, and equals signs.

string

Authorizationheaderrequired

HTTP Basic credentials (Basic base64(clientId:clientSecret)) for a client authorized to delete links in the target project.

string

Responses

204

Link deleted successfully. No content returned. The operation is idempotent.

400application/json

Invalid request. The alias parameter does not match the required format.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

401application/json

Unauthorized. The Authorization header is missing, malformed, or contains invalid credentials.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

403application/json

Forbidden. The authenticated client does not have permission to delete links for this project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Link not found. The specified alias does not exist or has already been deleted.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

429application/json

Too many requests. Rate limit exceeded for the current user or project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

get/links/{alias}

Retrieves the latest metadata for a short link identified by its alias. Use this endpoint to confirm TTL, key protection, client type, and generated code verifier values.

  • The alias is the string value returned during creation.
  • Successful responses include the same shape as link creation.

Parameters

aliaspathrequired

The unique identifier (alias) of the link to retrieve. This is the base64-encoded value returned when the link was created.

string

Authorizationheaderrequired

HTTP Basic credentials (Basic base64(clientId:clientSecret)) for a client permitted to read link details for the project.

string

Responses

200application/json

Link details retrieved successfully. Returns the complete metadata for the link.

object

  • projectIdstring / uuid

    Project UUID (v4) that owns the link.

  • destinationUrlstring

    Redirect target URL returned when the link is accessed. Present for url, deep, and redirect-style jwt links. Null for json and inline jwt links.

  • pathstring

    Relative path assigned to the link (without domain). Auto-generated as a unique identifier unless a custom path was supplied during creation.

  • rawJsonobject

    JSON payload returned to callers for json links. Omitted for other link types. The payload adheres to platform limits (nesting depth ≤ 4, arrays ≤ 10 items, string length ≤ 192 characters, key length ≤ 32 characters).

  • jwtClaimsobject

    Claims stored for JWT-based links (jwt or deep type). Reserved top-level claims (iss, iat, exp, nbf, jti, path, queryString, fragment) are populated automatically by the platform and not included here.

  • shortUrlstring

    Fully-qualified URL that end users visit to access the link. Includes the generated key query parameter when keyProtected is true (e.g., https://myproject.dyly.dev/my-custom-path?key=abc123).

  • aliasstring

    The unique identifier for the link (base64-encoded). Use this value with lookup, update, and deletion APIs. Length: 1-1024 characters.

  • expiresInnumber

    Remaining lifetime in seconds before the link expires and becomes inaccessible. null or 0 indicates the link does not expire automatically.

  • jwtExpiresInnumber

    Lifetime in seconds for JWT tokens produced by the link (between 300 and 86,400 seconds). Only populated for jwt and deep links.

  • createdAtstring / date-time

    ISO 8601 timestamp indicating when the link was created.

  • oneTimeboolean

    Indicates whether the link can be consumed only once. After the first access, the link becomes invalid.

  • typestring

    Link type stored for the resource. Possible values: url (simple redirect), json (returns JSON payload), jwt (issues signed token), or deep (app deep link with token).

  • keyProtectedboolean

    True when the link requires a key query parameter for access. The key value is included in shortUrl when this is enabled.

  • flowstring

    JWT retrieval flow when the link was created with a redirect (implicit appends token to fragment, code issues authorization code). Only present for jwt links with destinationUrl.

  • domainstring

    Fully qualified domain name hosting the link.

  • codeVerifierstring

    PKCE code verifier generated for JWT code flow links. Returned during creation so public clients can exchange the authorization code. Only present for jwt links with flow: code.

  • clientTypestring

    Client classification associated with the link (public or confidential). Present for JWT code flow links and determines the authentication requirements.

400application/json

Invalid request. The alias parameter does not match the required format.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

401application/json

Unauthorized. The Authorization header is missing, malformed, or contains invalid credentials.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

403application/json

Forbidden. The authenticated client does not have permission to read links for this project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Link not found. The specified alias does not exist.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

429application/json

Too many requests. Rate limit exceeded for the current user or project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

put/links/{alias}

Updates mutable properties of an existing short link identified by its alias.

Updatable properties:

  • destinationUrl: Can only be changed if originally specified. Cannot be added if the link was created without it, and cannot be removed once set.
  • rawJson: Only for links of type: json. Updates the JSON payload returned when the link is accessed.
  • jwtClaims: Only for links of type: jwt. Updates the JWT claims used to generate tokens.
  • jwtExpiresIn: Only for links of type: jwt. Updates the JWT token expiration time (in seconds).
  • expiresIn: Updates the link's time-to-live. If the project lacks the LinkTtl capability, this value may be ignored or coerced to a default of 24 hours. Positive values must be at least 60 seconds.

Immutable properties: The following properties cannot be changed after creation: projectId, domain, path, alias, type, oneTime, keyProtected, flow, clientType.

Validation:

  • The alias must belong to a link in the authenticated project.
  • Property updates must be consistent with the link's type (e.g., rawJson can only update json links).
  • A request with no valid updates returns a success response without changing the link.

Response: Returns the updated link metadata in the same format as link creation and retrieval.

Parameters

aliaspathrequired

The unique identifier (alias) of the link to update. This is the base64-encoded value returned when the link was created.

string

Authorizationheaderrequired

HTTP Basic credentials (Basic base64(clientId:clientSecret)) for a client authorized to update links in the target project.

string

Request body

Required · application/json

object

  • destinationUrlstring / uri

    The destination URL to redirect users to. Can only be updated if the link was originally created with a destinationUrl. Cannot be added if not originally present, and cannot be removed once set. Must be a valid absolute http(s) URL.

  • rawJsonobject

    JSON payload returned when accessing the link. Only for links with type: json. Must satisfy the same validation rules as during creation (max depth 4, max array length 10, max string length 192 characters).

  • jwtClaimsobject

    JWT claims to include in generated tokens. Only for links with type: jwt. The same reserved keys (iss, iat, exp, nbf, jti, path, queryString, fragment) apply and will be automatically managed by the service.

  • jwtExpiresIninteger

    JWT token expiration time in seconds. Only for links with type: jwt. Must be between 300 (5 minutes) and 86400 (24 hours).

  • expiresIninteger

    Link time-to-live in seconds. Zero indicates unlimited (if project capabilities allow). Positive values must be at least 60 seconds. Maximum is 31536000 (1 year). Projects without the LinkTtl capability may have this value coerced to 24 hours.

Responses

200application/json

Link updated successfully. Returns the complete updated metadata for the link.

object

  • projectIdstring / uuid

    Project UUID (v4) that owns the link.

  • destinationUrlstring

    Redirect target URL returned when the link is accessed. Present for url, deep, and redirect-style jwt links. Null for json and inline jwt links.

  • pathstring

    Relative path assigned to the link (without domain). Auto-generated as a unique identifier unless a custom path was supplied during creation.

  • rawJsonobject

    JSON payload returned to callers for json links. Omitted for other link types. The payload adheres to platform limits (nesting depth ≤ 4, arrays ≤ 10 items, string length ≤ 192 characters, key length ≤ 32 characters).

  • jwtClaimsobject

    Claims stored for JWT-based links (jwt or deep type). Reserved top-level claims (iss, iat, exp, nbf, jti, path, queryString, fragment) are populated automatically by the platform and not included here.

  • shortUrlstring

    Fully-qualified URL that end users visit to access the link. Includes the generated key query parameter when keyProtected is true (e.g., https://myproject.dyly.dev/my-custom-path?key=abc123).

  • aliasstring

    The unique identifier for the link (base64-encoded). Use this value with lookup, update, and deletion APIs. Length: 1-1024 characters.

  • expiresInnumber

    Remaining lifetime in seconds before the link expires and becomes inaccessible. null or 0 indicates the link does not expire automatically.

  • jwtExpiresInnumber

    Lifetime in seconds for JWT tokens produced by the link (between 300 and 86,400 seconds). Only populated for jwt and deep links.

  • createdAtstring / date-time

    ISO 8601 timestamp indicating when the link was created.

  • oneTimeboolean

    Indicates whether the link can be consumed only once. After the first access, the link becomes invalid.

  • typestring

    Link type stored for the resource. Possible values: url (simple redirect), json (returns JSON payload), jwt (issues signed token), or deep (app deep link with token).

  • keyProtectedboolean

    True when the link requires a key query parameter for access. The key value is included in shortUrl when this is enabled.

  • flowstring

    JWT retrieval flow when the link was created with a redirect (implicit appends token to fragment, code issues authorization code). Only present for jwt links with destinationUrl.

  • domainstring

    Fully qualified domain name hosting the link.

  • codeVerifierstring

    PKCE code verifier generated for JWT code flow links. Returned during creation so public clients can exchange the authorization code. Only present for jwt links with flow: code.

  • clientTypestring

    Client classification associated with the link (public or confidential). Present for JWT code flow links and determines the authentication requirements.

400application/json

Invalid request. Validation failed for one or more parameters (e.g., trying to add destinationUrl when not originally specified, updating properties not allowed for the link type).

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

401application/json

Unauthorized. The Authorization header is missing, malformed, or contains invalid credentials.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

403application/json

Forbidden. The authenticated client does not have permission to update links for this project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Link not found. The specified alias does not exist.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

429application/json

Too many requests. Rate limit exceeded for the current user or project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

post/links/{alias}/jwt

Exchanges a one-time authorization code for a signed JWT issued for the specified short link alias.

  • Accepts both confidential and public clients. Confidential clients must supply clientSecret; public clients must provide the codeVerifier that was generated during link creation.
  • The code value is single-use and expires shortly after issuance. Requests with an incorrect code, mismatched alias, or mismatched client type return 400.
  • The endpoint validates stored PKCE data when available.
  • Successful responses return the JWT and a derived JWKS URI.

Parameters

aliaspathrequired

The unique identifier (alias) of the JWT-protected link. This is the base64-encoded value associated with the authorization code.

string

Request body

Required · application/x-www-form-urlencoded

object

  • coderequiredstring

    One-time authorization code to exchange for a JWT. Codes are exactly 32 characters, expire shortly after issuance, and can only be used once.

  • clientIdrequiredstring / uuid

    Client application identifier (UUID v4). Must correspond to the client configured for the link and be a valid UUID format.

  • clientTyperequiredstring

    Classification of the client making the request. Accepts confidential or public and must match the link configuration.

  • clientSecretstring

    Required when clientType is confidential. Provide the stored client secret value issued by DyLy. Length: 64-96 characters.

  • codeVerifierstring

    PKCE code verifier tied to the authorization code. Mandatory for public clients and optional for confidential clients. Length: 1-256 characters.

Responses

200application/json

JWT exchanged successfully. Returns the signed JWT and JWKS URI.

object

  • jwtstring

    Signed JWT (JSON Web Token) generated for the link. The payload reflects the stored jwtClaims plus service-managed claims (iss, iat, exp, nbf, jti). Use the jwksUri to retrieve the public keys for signature validation.

  • jwksUristring / uri

    JWKS (JSON Web Key Set) endpoint URI that exposes the public keys used to validate the JWT signature. This endpoint follows the standard JWKS format (RFC 7517).

400application/json

Invalid request. The authorization code is invalid, expired, or parameters are malformed. Also returned when PKCE validation fails.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

401application/json

Unauthorized. The client credentials (clientId/clientSecret or codeVerifier) are invalid or missing.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

403application/json

Forbidden. The client does not have permission to exchange this authorization code.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Link not found. The specified alias does not exist or the authorization code has already been consumed.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

429application/json

Too many requests. Rate limit exceeded for the current client.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

get/clicks

get click analytics

#list-clicks

Retrieves click analytics for a specific domain. Combine query parameters to fetch detailed click events, aggregated counts, geographic distributions, or time-series buckets.

Usage patterns

  • Provide domain to retrieve analytics for all links under that domain.
  • Use groupBy to narrow the aggregation (e.g., day, hour, location).
  • Use fillZero=true with groupBy=day or hour to include zero-count buckets in time-series responses.
  • Pagination is supported through maxItemCount and continuationToken.

Standard plan (or higher) is required; Free plan clients receive 403 responses.

Parameters

domainqueryrequired

Domain to retrieve click analytics for. Must match a domain registered for the authenticated project.

string

groupByquery

Aggregation granularity. day and hour return temporal buckets, while location aggregates by country. Omit for raw click events.

string

enum: day, hour, location

countryquery

ISO 3166-1 alpha-2 country code filter. Provide Unknown to include traffic without a resolved country. Applies only when groupBy=location.

string

fillZeroquery

When true, returns zero-count entries for missing time buckets. Valid only with groupBy=day or hour.

boolean

startDatequery

Start timestamp (UTC, ISO 8601). Defaults to 30 days before endDate when omitted. The maximum supported range is 90 days.

string / date-time

endDatequery

End timestamp (UTC, ISO 8601). Defaults to the current instant when omitted. Must be greater than startDate.

string / date-time

maxItemCountquery

Maximum items per page. Values outside the 1-1000 range are clamped to the nearest boundary.

integer

continuationTokenquery

Opaque pagination token returned by a previous response. Supply this to fetch the next page of results.

string

Authorizationheaderrequired

HTTP Basic credentials (Basic base64(clientId:clientSecret)) or Bearer JWT token authorised for Standard plan analytics. The credentials must map to the target project or alias.

string

Responses

200application/json

Click analytics retrieved successfully. The response shape depends on the requested aggregation.

object

  • domainstring

    Domain for which click analytics were retrieved.

  • groupBystring

    Aggregation mode applied to the response, when requested.

  • fillZeroboolean

    Indicates whether zero-count buckets were returned.

  • countrystring

    Country filter applied to the query, if any.

  • totalCountinteger / int64

    Total clicks matching the query criteria.

  • startDatestring / date-time

    Analytics window start time (UTC).

  • endDatestring / date-time

    Analytics window end time (UTC).

  • continuationTokenstring

    Token to request the next page of results. Present when more data is available.

  • clicksarray

    Detailed click events or aggregated buckets when groupBy is day or hour.

    array

    Detailed click events or aggregated buckets when groupBy is day or hour.

    Items

    oneOf

    object

    • timestamprequiredstring / date-time

      Timestamp (UTC, ISO 8601) indicating when the click occurred.

    • aliasrequiredstring

      Short link alias associated with the click event.

    • countryrequiredstring

      ISO 3166-1 alpha-2 country code of the visitor. Returns Unknown when the location cannot be resolved.

    oneOf

    object

    • datestring / date

      Date bucket in YYYY-MM-DD format when groupBy=day.

    • hourstring / date-time

      Hour bucket (ISO 8601, top of the hour) when groupBy=hour.

    • countrequiredinteger / int64

      Total click count for the bucket.

  • locationsarray

    Country-level aggregates returned when groupBy=location.

    array

    Country-level aggregates returned when groupBy=location.

    Items

    object

    • countryrequiredstring

      ISO 3166-1 alpha-2 country code or Unknown when the visitor location cannot be determined.

    • countrequiredinteger / int64

      Total click count originating from the country.

  • timeseriesarray

    Time-series buckets, especially when fillZero=true.

    array

    Time-series buckets, especially when fillZero=true.

    Items

    object

    • datestring / date

      Date bucket in YYYY-MM-DD format when groupBy=day.

    • hourstring / date-time

      Hour bucket (ISO 8601, top of the hour) when groupBy=hour.

    • countrequiredinteger / int64

      Total click count for the bucket.

400application/json

Invalid request parameters (e.g., missing domain, invalid date range, unsupported groupBy value).

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

401application/json

Unauthorized. The Authorization header is missing, malformed, expired, or contains invalid credentials.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

403application/json

Forbidden. The caller lacks access to the target project, or the plan does not include click analytics.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Domain not found, or analytics unavailable for the requested scope.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

429application/json

Too many requests. Rate limit exceeded for the client or project.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

503application/json

Service unavailable. Downstream analytics service (e.g., Synapse) could not be reached after retries.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

504application/json

Gateway timeout. The analytics query timed out before completion.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.