canonical: https://jentic.com/apis/golinks.io/golinks

# GoLinks API

The GoLinks API provides 8 endpoints for managing go/links - short, memorable internal URLs that resolve to long company resources such as docs, dashboards, and runbooks. It covers full CRUD over golinks by name, daily redirect metrics, and user listing and search inside a workspace. Authentication is a workspace-level bearer token, and resolution stays inside the company namespace so links never leak outside the organisation.

## For AI agents

Create, update, and look up internal go/links and read their daily redirect metrics across a GoLinks workspace.

## Scope

Does not handle public branded short links, click fraud detection, or QR-code generation - use for internal company go/link CRUD, redirect metrics, and workspace user lookup only.

## Capabilities

- Create a memorable go/link that resolves to a long internal URL
- Edit the destination of an existing go/link without changing its short name
- List every go/link in the workspace with pagination support
- Retrieve daily redirect metrics for usage and adoption reporting
- Search for users in the workspace by name or email
- Delete a go/link when the underlying resource is decommissioned

## Use cases

### Internal Knowledge Routing

Engineering and operations teams use GoLinks to give every important internal resource a short, memorable handle (go/oncall, go/handbook, go/runbook). The API lets platform teams script bulk creation during onboarding, keep destinations fresh as docs move, and audit unused links - all without manual editing in the GoLinks UI.

Example prompt: Create the go/links go/handbook, go/oncall, and go/runbook pointing to the matching Notion and PagerDuty URLs.

### Adoption Reporting

Platform teams measure how widely internal documentation is reaching the company by pulling the daily redirect metrics endpoint into a dashboard. Low-traffic links flag stale or undiscovered docs, while spikes reveal the resources actually driving day-to-day work.

Example prompt: Pull the last 30 days of redirect metrics from `/metrics/redirects` and produce a CSV of the top 20 most-used go/links.

### Lifecycle Cleanup of Stale Links

Over time a workspace accumulates go/links pointing to deprecated dashboards or archived projects. The API's list, retrieve, and delete operations let an automation script enumerate every link, check redirect counts, and prune anything below a threshold so the namespace stays trustworthy.

Example prompt: List every go/link, find ones with zero redirects in the last 90 days, and delete them.

### AI Agent Resource Lookup via Jentic

An AI assistant answering employee questions can resolve go/links to their canonical destinations before fetching the underlying doc, so 'what's go/handbook?' returns the live URL rather than a stale answer. Through Jentic the agent searches by intent, loads the GET `/golinks/{name}` schema, and executes against the workspace bearer token held in the vault.

Example prompt: Look up the go/link named 'handbook' and return the destination URL it currently resolves to.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/golinks` | List all golinks |
| POST | `/golinks` | Create a golink |
| GET | `/golinks/{name}` | Retrieve a golink by name |
| PUT | `/golinks/{name}` | Edit a golink |
| DELETE | `/golinks/{name}` | Delete a golink |
| GET | `/metrics/redirects` | Daily redirect metrics |
| GET | `/users/search` | Search workspace users |

## Key resources

- **Golinks** — Create, retrieve, edit, list, and delete go/links by name
- **Metrics** — Read daily redirect metrics across the workspace
- **Users** — List and search users in the GoLinks workspace

## Why Jentic

- **Setup:** Wiring GoLinks by hand means implementing its bearer auth against api.golinks.io, scoping calls to a single workspace, and mapping the go/link CRUD and redirect-metrics endpoints yourself. Through Jentic you install once, import GoLinks from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** GoLinks puts the link name in the URL path (`/golinks/{name}`) but scopes the token to one workspace, so scope the agent to the operations it needs, such as creating a go/link or reading redirect metrics. You choose the operations it may call, so deleting a go/link is not included unless you add it.
- **Credential handling:** Your GoLinks token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an internal go link' or 'check redirect metrics', and Jentic returns the matching GoLinks operation with its input schema so the agent calls the right endpoint without reading the API reference.

## Related APIs

- **Bitly** — Public-facing short link platform with branded domains and global redirect analytics.
- **Rebrandly** — Branded short link API with custom domains and per-link tracking.
- **Notion API** — Backs the docs that go/links most often resolve to.

## FAQ

### What authentication does the GoLinks API use?

The GoLinks API uses bearer token authentication (bearerAuth) on the Authorization header. Tokens are workspace-scoped, and through Jentic they are stored encrypted in the vault so the raw token never enters the agent's context.

### Can I create a go/link with the GoLinks API?

Yes. POST /golinks accepts a name and a destination URL, and the link is immediately resolvable from go/{name} inside the workspace. Use GET `/golinks/{name}` first if you need to check that the name is free.

### What are the rate limits for the GoLinks API?

GoLinks applies per-workspace rate limits documented at help.golinks.io. The OpenAPI spec does not encode exact numbers, so check the GoLinks support docs before running bulk imports of more than a few hundred links.

### How do I report on go/link usage through Jentic?

Search Jentic for 'go link redirect metrics', load the schema for GET `/metrics/redirects`, and execute. Jentic injects the bearer token at execution and returns the daily redirect counts so an agent can build adoption dashboards without writing an HTTP client.

### Can the API list users in my workspace?

Yes. GET /users returns every user in the GoLinks workspace and GET `/users/search` filters by query string, which is useful for matching go/link owners to people during audits.

### Does the GoLinks API support public short links like bit.ly?

No. GoLinks resolves only inside the company workspace and the API only manages internal go/links. For public-facing branded short URLs use Bitly or Rebrandly instead.

### Can I limit what my agent is allowed to do with the GoLinks API?

Yes. Because Jentic One is self-hosted and governed by your own rules, you decide exactly which GoLinks operations the agent may call, so you can grant it read-only work like listing go/links (GET /golinks) or pulling redirect metrics (GET `/metrics/redirects`) while withholding write actions. Destructive calls such as DELETE `/golinks/{name}` or edits via PUT `/golinks/{name}` are not available to the agent unless you explicitly add them. The bearer token stays scoped to a single workspace, so resolution never leaves your company namespace and the agent only ever acts inside that workspace.