Authentication
Every endpoint requires an API key, sent as a bearer token in the Authorization header. You generate the key in your account settings and you can rotate it there.
Treat it like any other credential. It goes in your secret store rather than in the repository, it is scoped to the account rather than to a single link, and rotating it invalidates anything still using the old value.
The base URL and the full endpoint list are published in the API documentation on the Digily Link site, which is the authoritative reference. Anything in this article that disagrees with it is out of date.
What failure looks like
Conventional HTTP status codes, with a JSON body carrying an errors array so you get a machine readable reason alongside the status.
- 200 the request completed.
- 400 required parameters are missing or invalid.
- 401 the API key is missing or invalid, which in practice usually means it was not sent at all.
- 404 the resource does not exist, or does not belong to this account.
- 429 the rate limit was exceeded.
- 500 a problem on the server side.
Handle 429 with a backoff rather than a retry loop. A pipeline that hammers a rate limited endpoint is how a five minute job becomes a twenty minute one.
The timezone gotcha
API results work in UTC unless an endpoint states otherwise. Dashboards generally display local time.
This produces a specific and irritating class of bug: numbers pulled from the API disagree with numbers read off a screen, by exactly one timezone offset, and everybody spends an afternoon on it.
Decide once which one your reporting uses, convert at the boundary, and write it down next to the code that does the conversion.
What the API reaches
More than links, which is useful when the link is only part of what you are automating.
- Links and link statistics, which is what most integrations start with.
- Projects, for grouping links that belong to the same piece of work.
- QR codes, so a printed asset can be generated in the same step as the link behind it.
- Tracking pixels and splash pages.
- Custom domains, teams and team members, for anything multi user.
- Account payments and logs, for reconciliation and auditing.
Where automation actually pays
Not everywhere. A handful of stable links are easier to manage by hand than to wrap in a script nobody remembers how to run.
It pays when links are generated rather than authored.
- One link per release, created by the pipeline and pointing at that release's notes.
- One link per customer or per project, created when the record is created.
- Bulk repointing after a docs migration, which is the case that justifies the whole approach.
- Pulling statistics into your own reporting so link data sits next to everything else.
Make the job safe to rerun
Pipelines get rerun. A create call that runs twice either fails on a duplicate path or produces a second link, and both are annoying in different ways.
Look the path up first and update it if it exists, create it if it does not. That turns the job into something you can rerun without thinking about it, which is the property you actually want from a release step.
Log the path and the resulting identifier on both branches. When something goes wrong three months later, that log is the only thing that tells you which run created what.