API basics

The Dynalinks REST API lets you create, update, list and delete links, shorten URLs, and manage the iOS and Android apps of a project from your own backend. This page covers the conventions shared by every endpoint. For the full endpoint reference, see API reference.

Base URLCopy Anchor Link

All endpoints live under a single versioned base URL:

https://dynalinks.app/api/v1

Always use https. Your project's subdomain (for example yourproject.dynalinks.app) serves your links, not the API.

AuthenticationCopy Anchor Link

Every request needs a project API key. You can find it in the console under Settings > API Keys. Send it in the Authorization header:

curl https://dynalinks.app/api/v1/links \
  --header 'Authorization: Token YOUR_API_KEY'

You can also pass it as an api_key query parameter. See API authorization for both options.

A key belongs to one project, so every request works on that project's data. You never pass a project ID.

Requests and responsesCopy Anchor Link

• Request and response bodies are JSON.
• POST, PATCH and PUT requests must send Content-Type: application/json. Without it, the API responds with 400 Bad Request.
• GET and DELETE requests take their parameters in the query string.
• Field names use snake_case, for example ios_fallback_url.
• Resources are identified by an id string (a UUID) that is returned when you create or list them.

curl --request POST https://dynalinks.app/api/v1/links \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"name": "Spring sale", "path": "sale/spring", "url": "https://example.com/sale"}'

Status codes and errorsCopy Anchor Link

Successful requests return:

Failed requests return a JSON body with a single error message:

{
  "error": "Missing or invalid api_key"
}

PaginationCopy Anchor Link

List endpoints (GET /api/v1/links, GET /api/v1/ios_apps, GET /api/v1/android_apps) return results one page at a time.

Both must be positive whole numbers. 0, negative values, or text return 400 Bad Request.

curl 'https://dynalinks.app/api/v1/links?page=2&limit=50' \
  --header 'Authorization: Token YOUR_API_KEY'

The response wraps the items in a named array and adds a meta object:

{
  "links": [
    { "id": "1f0c6e9a-2b7d-4c1e-9a4f-6d2b8e3c5a71", "name": "Spring sale", "path": "sale/spring", "...": "..." }
  ],
  "meta": {
    "page": 2,
    "limit": 50,
    "count": 134,
    "last": 3,
    "from": 51,
    "to": 100,
    "previous": 1,
    "next": 3
  }
}

The meta object may include additional fields (such as page URLs). Rely only on the ones listed above.

To fetch everything, keep requesting the next page until next is missing. Asking for a page past the end returns 200 with an empty array, not an error.

Filtering and sortingCopy Anchor Link

List endpoints accept filters in a q parameter. Each filter is written as q[<field>_<condition>]=<value>.

Common conditions:

Fields you can filter links by:

The fields available for iOS and Android apps are listed in iOS and Android apps API.

To sort, pass q[s] with a field name and asc or desc:

curl --get https://dynalinks.app/api/v1/links \
  --header 'Authorization: Token YOUR_API_KEY' \
  --data-urlencode 'q[path_start]=products/' \
  --data-urlencode 'q[s]=created_at desc' \
  --data-urlencode 'limit=100'

You do not need to filter by path before creating a link. Use the upsert endpoint to create or update a link in one request.

Deleting a linkCopy Anchor Link

Delete a link with its id, the UUID returned when the link was created or listed. The link path does not work here.

curl --request DELETE https://dynalinks.app/api/v1/links/1f0c6e9a-2b7d-4c1e-9a4f-6d2b8e3c5a71 \
  --header 'Authorization: Token YOUR_API_KEY'

A successful delete returns 204 No Content with an empty body. An unknown id returns 404 Not Found.

If you only know the path, look the link up first and use the id from the result:

curl --get https://dynalinks.app/api/v1/links \
  --header 'Authorization: Token YOUR_API_KEY' \
  --data-urlencode 'q[path_eq]=sale/spring'

Rate limitsCopy Anchor Link

Write requests are rate limited per API key. Read requests and deletes of links are not rate limited.

The endpoints in one row share a single budget. For example, 400 link creates and 200 link updates in the same minute use up the link writes limit for that key, while URL shortening still has its own 600. Each API key has its own budgets.

When you go over a limit, the API responds with:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"error": "Rate limit exceeded. Too many requests."}

The response does not include a Retry-After header. Wait a few seconds and retry, ideally with exponential backoff. If you need to create a large number of links, spread the requests out over time instead of sending them in parallel bursts.

Full referenceCopy Anchor Link

Every endpoint, parameter and response field is documented in the API reference. Related guides:

• API authorization
• URL shortening
• Unnamed links
• iOS and Android apps API