GoLinks API Documentation (2.0.0)

Download OpenAPI specification:

Introduction

Welcome to the GoLinks API! You can use this API to access our endpoints, such as the Go Links API, to create go links that you and everyone in your workspace can use, read workspace users and go link analytics, run searches and export the audit log. To access the API you need to be on the GoLinks Enterprise plan. You can upgrade to the Enterprise plan on the billing page. If you have any questions about the Enterprise plan, reach out to the Sales team.

Authentication

Every request must carry a credential in the Authorization header. The GoLinks API supports two kinds:

Credential	Use it for	Where it comes from
API token	Scripts and integrations that you run yourself	Developer Tools › API
OAuth 2.0 access token	Apps and integrations you build that other people in the workspace authorize	Developer Tools › OAuth Apps

API tokens

Any user with the Developer Tools permission on an Enterprise workspace can create and revoke tokens. Non-admins only see their own tokens, while admins see every token in the workspace. Requests made with a token act as the user who created it, so do not share your token with other users or put it in publicly accessible places such as GitHub. If a token is compromised, revoke it and create a new one.

Create an access token

Sign in to GoLinks, open Developer Tools › API and click Create token. Give the token a name and choose:

Permissions – whether the token may also return your own unlisted and private go links. By default a token only sees the go links that everyone in the workspace can see.
Expiration – 7, 30, 90 (default), 180 or 365 days, or never. Expired tokens are rejected with a 401 and cannot be renewed; create a new token and update your integration.

The raw token is shown once the token is created. You can view it again, rename the token or revoke it at any time from the same table.

How to use your access token

Requests are authenticated with HTTP Bearer authentication. Provide the token in the Authorization header:

Authorization: Bearer {ACCESS_TOKEN}

If you do not provide a token, or the token is invalid, expired or revoked, you receive a 401 response:

{
  "error": {
    "message": "An error occurred",
    "code": 401,
    "type": "not_authorized",
    "request_id": "56A14568A9F05AFB"
  }
}

OAuth 2.0

Workspace admins can register apps in Developer Tools › OAuth Apps by giving the app a name, its redirect URIs and the scopes it may request; GoLinks generates the client_id. Apps you register are private to your workspace: only members of your workspace can authorize them, and the consent screen tells them the app has not been verified by GoLinks. Registered apps use the Authorization Code flow with PKCE. Apps are public clients: there is no client secret, the code_verifier proves possession of the authorization code instead.

Send the user to https://www.golinks.io/oauth_authorize.php with the query parameters response_type=code, client_id, redirect_uri (must exactly match one of the URIs registered for the app), scope (space separated, see below), state, code_challenge and code_challenge_method=S256.
The user signs in to GoLinks and approves the requested scopes. GoLinks redirects back to redirect_uri with code and state. The code is single use and expires after 10 minutes.
Exchange the code at POST /oauth/token with grant_type=authorization_code and the code_verifier. The response contains an access token that is valid for one hour and a refresh token.
Call the API with Authorization: Bearer {ACCESS_TOKEN}. When the access token expires, call POST /oauth/token with grant_type=refresh_token. Every refresh rotates both tokens; presenting an already rotated refresh token revokes the whole grant and the user has to authorize the app again.
Revoke tokens you no longer need with POST /oauth/revoke.

Scope	Grants
`golinks:read`	Read go links and go link metrics
`golinks:write`	Create, update and delete go links
`search:read`	Run workspace searches
`users:read`	List workspace users
`admin:read`	Read the workspace audit log (the authorizing user must be an admin)

An access token that lacks the scope an endpoint requires is rejected with 403 and the body {"error": "insufficient_scope", "error_description": "Insufficient scope."}.

API Overview

The GoLinks API is REST-based and uses standard HTTP verbs and status codes. All requests must be made over HTTPS and every response body is JSON.

Base URL

The base URL of the GoLinks API is https://api.golinks.io. For example, to access the go links endpoint, append the endpoint path to the base URL: https://api.golinks.io/golinks.

Request format

The go link endpoints (POST, PUT and PATCH /golinks, POST /golinks_bulk) accept form-encoded request bodies only. Send exactly Content-Type: application/x-www-form-urlencoded (no charset suffix); any other content type is rejected with 415. Arrays use bracket notation, for example tags[]=drive&tags[]=docs or geolinks[0][location]=US&geolinks[0][url]=https://example.com/us.
The OAuth endpoints accept form-encoded or application/json bodies.

Errors

All responses include a standard HTTP status code. The successful status codes are:

HTTP Status Code	Description
200 OK	The request was successful.
201 Created	The resource has been created.

Errors carry extra information about why the request was not successful. The error body has the following format:

{
  "error": {
    "message": "Descriptive information about the error",
    "code": 409,
    "type": "conflict",
    "request_id": "56A14568A9F05AFB"
  }
}

message is currently the generic text An error occurred for most failures. Use type and code to decide how to handle an error and quote the request_id when you contact support, so we can look up the details of the failed request. The error status codes, along with their error types, are:

HTTP Status Code	Error Type	Description
400 Bad Request	bad_request	The request cannot be accepted, for example because the request body is empty.
401 Unauthorized	not_authorized	The token is missing, invalid, expired or revoked.
403 Forbidden	forbidden	The token is not allowed to use this method on this endpoint, or the user lacks the required permission.
404 Not Found	not_found	The resource was not found.
405 Method Not Allowed	method_not_allowed	The request method is not supported by the endpoint.
408 Request Timeout	request_timed_out	The request took too long to process; retry later.
409 Conflict	conflict	The request conflicts with an existing resource, for example creating a go link whose name is already taken or reserved.
415 Unsupported Media Type	invalid_content_type	The request content type is not supported.
422 Unprocessable Entity	missing_field or invalid_request	The request contains errors, such as required fields that are missing or values that fail validation.
429 Too Many Requests	rate_limit_exceeded	The rate limit has been exceeded. Wait and retry.
500 Internal Server Error	internal_server_error	Something went wrong with the GoLinks API.

The OAuth endpoints return RFC 6749 style errors instead, for example {"error": "invalid_grant", "error_description": "Authorization code has expired."}. The one exception is a request that leaves out a required parameter, which is rejected with the standard 422 envelope shown above.

Rate Limiting

Rate limits are enforced per endpoint and HTTP method for every client and are independent of how many API tokens you create:

a burst limit of 80 requests per 10-second window, and
a daily quota that depends on your plan (500,000 requests per endpoint per day on the Enterprise plan).

If you exceed a limit you receive a 429 status code with the following body:

{
  "error": {
    "message": "An error occurred",
    "code": 429,
    "type": "rate_limit_exceeded",
    "request_id": "56A14568A9F05AFB"
  }
}

Every response contains information about the rate limit in the HTTP headers.

HTTP Header	Description
RateLimit-Limit	The maximum number of requests allowed in the current window (the burst limit, or the daily quota once it is the limit you hit).
RateLimit-Remaining	The number of requests remaining in the current window.
Retry-After	The number of seconds to wait before retrying. Only sent when the rate limit has been exceeded.

Pagination

All endpoints that return a list come with a metadata object that contains pagination information. Use the limit and offset query parameters to choose how many results to return and how many to skip. You can fetch the next page through the URL in metadata.links.next; when there are no more results the value is null.

Pagination Parameters	Description
limit	The maximum number of results per page. Defaults to 50 (go links, users), 100 (search) or 20 (audit log); the maximum is 1000 for go links and 100 elsewhere.
offset	The number of results to skip. Defaults to 0.
count	The number of results in the current page.
total_results	The total number of results found.
links.next	The URL of the next page of results, or `null`.
links.prev	The URL of the previous page of results, or `null`.

Timestamps

Unless stated otherwise, timestamps are integers measured in seconds since the Unix epoch.

Support

If you have any questions about the API or run into errors, reach out to [email protected].

Go Links

The Go Links API lets you retrieve, create, update and delete the go links of your workspace. Go links can be shared with everyone in the workspace, be unlisted (only people who know the name can use them), private (only the owner can use them) or public (usable by people outside the workspace). A go link can also be a variable link (the URL contains {*} placeholders filled in from the typed name), a multi-link (opens several other go links at once) or a geo link (different destinations per country or US state).

List go links or retrieve a go link by name

https://api.golinks.io/golinks

Retrieve the go links of your workspace, sorted by their weekly, daily and monthly redirect hits. Pass sort=created_at or sort=updated_at to order by date instead (most recent first). By default, pinned links are listed before all other links, in the same order. Pass pinned-first=false to sort pinned links along with the rest.

Only go links that everyone in the workspace can see are returned. Tokens created with the unlisted or private permission also return the token owner's own unlisted or private links.

To fetch a single go link by name, pass the name query parameter (for example https://api.golinks.io/golinks?name=drive). Alias names resolve to their go link. The response is then a single go link object instead of a paginated list.

Authorizations:

ApiTokenOAuth2

query Parameters

limit	integer [ 1 .. 1000 ] Default: 50 Number of go links per page.
name	string <= 50 characters Example: name=drive Return the single go link (or alias) with this name instead of a list.
offset	integer >= 0 Default: 0 Number of go links to skip.
pinned-first	string Default: "true" Enum: "true" "false" List pinned go links before all other links. Set to `false` to sort pinned links along with the rest.
sort	string Enum: "created_at" "updated_at" Sort by creation or last update date (most recent first). Any other value sorts by creation date. Omit to sort by redirect hits.

Responses

Request samples

cURL

curl "https://api.golinks.io/golinks?limit=50&offset=0" \
  -H "Authorization: Bearer $GOLINKS_TOKEN"

Response samples

Content type

application/json

Example

List of go links

{"metadata": {"limit": 50,
"offset": 0,
"count": 50,
"total_results": 400,
"links": {"prev": null,
"next": "https://api.golinks.io/golinks?limit=50&offset=50"
}
},
"results": [{"gid": 12130,
"cid": 12,
"user": {"uid": 484371,
"first_name": "Test",
"last_name": "User",
"username": "test.user",
"email": "[email protected]",
"user_image_url": "https://www.gravatar.com/avatar/94d093eda664addd6e450d7e9881bcad?s=32&d=identicon&s=200&r=pg"
},
"url": "https://drive.google.com/drive/",
"name": "drive",
"description": "Company shared Google Drive",
"app_domain": "google.com",
"tags": [{"tid": 79,
"name": "drive"
}
],
"aliases": [{"aid": 512,
"gid": 12130,
"name": "gdrive",
"url": "https://drive.google.com/drive/"
}
],
"aliases_total_count": 1,
"collections": [ ],
"collections_count": 0,
"unlisted": 0,
"private": 0,
"variable_link": 0,
"pinned": 0,
"redirect_hits": {"daily": 100,
"weekly": 100,
"monthly": 100,
"alltime": 100
},
"created_at": 1576577874,
"updated_at": 1576577874
}
]
}

Create a go link

https://api.golinks.io/golinks

Create a new go link. The link is created for the token owner unless uid names another active user. You can view the newly created go link in your dashboard at https://app.golinks.io?filter=new.

The request body must be form-encoded (Content-Type: application/x-www-form-urlencoded). Optional features such as tags, aliases, multi-links, geo links and public, unlisted or private links depend on your plan and on the workspace settings; requests that use a feature the workspace does not have are rejected with 422.

Authorizations:

ApiTokenOAuth2

Request Body schema: application/x-www-form-urlencoded
required

name required	string <= 50 characters The go link name. Letters, numbers, emojis, `-` and `_` are allowed; the name is stored in lowercase. Names that are already used by a go link or alias, and reserved names, are rejected with 409.
aliases[]	Array of strings <= 10 items [ items <= 50 characters ] Additional names for the same link. Every alias must be unused by any go link or alias. Not supported for private links.
	Array of objects <= 50 items Collections to add the go link to, sent as `collections[<i>][name]`. Missing collections are created.
create_source	string Free-form label of the integration or script creating the link, shown in creation analytics.
description	string <= 500 characters Brief description of the link.
format	integer Default: 0 Enum: 0 1 `1` strips characters that are not allowed in go link names (for example punctuation) from `name` instead of rejecting it.
	Array of objects (Geo link mapping) Create a geo link with different destinations per location, sent as `geolinks[<i>][location]` and `geolinks[<i>][url]`. Visitors from other locations get `url`. A geo link cannot be private or a multi-link.
hyphens	integer Default: 0 Enum: 0 1 Requires `format=1`. `1` replaces spaces in `name` with hyphens; `0` removes them.
multilink_gids[]	Array of integers <= 10 items Create a multi-link that opens these go links. Targets must exist in your workspace and cannot be multi-links themselves. When set, `url` must be omitted. A multi-link cannot be private, public or a geo link.
private	integer Default: 0 Enum: 0 1 `1` makes the link private: only you can see and use it. Links cannot be changed to or from private after creation.
public	integer Default: 0 Enum: 0 1 `1` makes the link usable by people outside your workspace. Requires public links to be enabled for the workspace.
tags[]	Array of strings <= 20 items [ items <= 100 characters ] Tags to organize the go link (letters and numbers only, up to 100 characters each). Tags are created when they do not exist yet.
uid	integer Create the go link on behalf of another active user in your workspace. Defaults to the token owner.
unlisted	integer Default: 0 Enum: 0 1 `1` makes the link unlisted: only you and the people you share the name with can use it. Cannot be combined with `public`.
url	string <uri> <= 8000 characters The destination URL, including the scheme (`https://`, `mailto:` ...). Workspaces that enforce HTTPS reject `http://` URLs, and domains blocked by your admin are rejected. Add `{*}` placeholders to create a variable link. Required unless `multilink_gids[]` is provided.

Responses

Request samples

cURL

curl -X POST https://api.golinks.io/golinks \
  -H "Authorization: Bearer $GOLINKS_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "name=drive" \
  --data-urlencode "url=https://drive.google.com/drive/" \
  --data-urlencode "description=Company shared Google Drive" \
  --data-urlencode "tags[]=drive" \
  --data-urlencode "aliases[]=gdrive" \
  --data-urlencode "geolinks[0][location]=US-CA" \
  --data-urlencode "geolinks[0][url]=https://drive.google.com/drive/california"

Response samples

Content type

application/json

{"gid": 12130,
"cid": 12,
"user": {"uid": 484371,
"first_name": "Test",
"last_name": "User",
"username": "test.user",
"email": "[email protected]",
"user_image_url": "https://www.gravatar.com/avatar/94d093eda664addd6e450d7e9881bcad?s=32&d=identicon&s=200&r=pg"
},
"url": "https://drive.google.com/drive/",
"name": "drive",
"description": "Company shared Google Drive",
"tags": [{"tid": 79,
"name": "drive"
}
],
"unlisted": 0,
"private": 0,
"variable_link": 0,
"pinned": 0,
"created_at": 1576577874,
"updated_at": 1576577874,
"aliases": [{"aid": 512,
"gid": 12130,
"name": "gdrive",
"url": "https://drive.google.com/drive/"
}
],
"multilinks": [ ],
"geolinks": [{"location": "US-CA",
"url": "https://drive.google.com/drive/california"
}
],
"geolink": true
}

Update a go link

https://api.golinks.io/golinks

Update an existing go link. PUT replaces the whole go link: the description, tags, aliases, collections, multi-link targets and geo link mappings you do not send are removed. Send action=pin or action=lock to only change the pinned or locked state.

Locked go links can only be edited by their owner or by an admin, and workspaces can restrict editing to admins and owners. The request body must be form-encoded.

Authorizations:

ApiTokenOAuth2

Request Body schema: application/x-www-form-urlencoded
required

gid required	integer ID of the go link to update.
action	string Enum: "pin" "lock" Pin/unpin (`pin`, with `pinned`) or lock/unlock (`lock`, with `locked`) the go link instead of editing it. When `action` is set every other field is ignored. Pinning requires the pin permission; locking requires the lock permission. Locked links can only be edited by their owner or an admin.
aliases[]	Array of strings <= 10 items [ items <= 50 characters ] The complete new alias set. Omitting the field removes every alias.
	Array of objects <= 50 items The complete new collection set, sent as `collections[<i>][name]`. Omitting the field removes the link from every collection.
description	string <= 500 characters
	Array of objects (Geo link mapping) The complete new list of geo link mappings, sent as `geolinks[<i>][location]` and `geolinks[<i>][url]`. Omitting the field removes every mapping.
locked	integer Enum: 0 1 Required when `action=lock`.
multilink_gids[]	Array of integers <= 10 items The complete new list of multi-link targets. Omitting the field turns a multi-link back into a regular link, which then needs `url`.
name	string <= 50 characters The new go link name. Required unless `action` is set.
pinned	integer Enum: 0 1 Required when `action=pin`.
public	integer Enum: 0 1 Defaults to `0` when omitted. Changing a link to public requires public links to be enabled and the create-public-links permission.
tags[]	Array of strings <= 20 items [ items <= 100 characters ] The complete new tag set. Omitting the field removes every tag.
unlisted	integer Enum: 0 1 Defaults to `0` when omitted.
url	string <uri> <= 8000 characters The new destination URL. Required unless `action` or `multilink_gids[]` is set.

Responses

Request samples

cURL
cURL (pin)

curl -X PUT https://api.golinks.io/golinks \
  -H "Authorization: Bearer $GOLINKS_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "gid=12130" \
  --data-urlencode "name=drive" \
  --data-urlencode "url=https://drive.google.com/drive/folder" \
  --data-urlencode "description=Company shared Google Drive folder" \
  --data-urlencode "tags[]=drive"

Response samples

Content type

application/json

Example

Edit a go link

{"status": "ok",
"gid": 12130,
"cid": 12,
"user": {"uid": 484371,
"first_name": "Test",
"last_name": "User",
"username": "test.user",
"email": "[email protected]",
"user_image_url": "https://www.gravatar.com/avatar/94d093eda664addd6e450d7e9881bcad?s=32&d=identicon&s=200&r=pg"
},
"url": "https://drive.google.com/drive/folder",
"name": "drive",
"description": "Company shared Google Drive folder",
"tags": [{"tid": 79,
"name": "drive"
}
],
"unlisted": 0,
"private": 0,
"variable_link": 0,
"pinned": 0,
"created_at": 1576577874,
"updated_at": 1600000000,
"aliases": [ ],
"multilinks": [ ],
"geolinks": [ ]
}

Update part of a go link

https://api.golinks.io/golinks

Partially update an existing go link. Only the fields you send are changed; tags, aliases, collections, multi-link targets, geo link mappings, the description and the visibility flags keep their current values when omitted. Send an empty array (for example tags[]=) to clear a list. action=pin / action=lock work exactly as with PUT. The request body must be form-encoded.

Authorizations:

ApiTokenOAuth2

Request Body schema: application/x-www-form-urlencoded
required

gid required	integer ID of the go link to update.
action	string Enum: "pin" "lock" Same as for `PUT`: pin/unpin or lock/unlock the link instead of editing it (with `pinned` or `locked`).
aliases[]	Array of strings <= 10 items [ items <= 50 characters ]
	Array of objects <= 50 items Sent as `collections[<i>][name]`.
description	string <= 500 characters
	Array of objects (Geo link mapping) Sent as `geolinks[<i>][location]` and `geolinks[<i>][url]`.
locked	integer Enum: 0 1
multilink_gids[]	Array of integers <= 10 items
name	string <= 50 characters
pinned	integer Enum: 0 1
public	integer Enum: 0 1
tags[]	Array of strings <= 20 items [ items <= 100 characters ]
unlisted	integer Enum: 0 1
url	string <uri> <= 8000 characters

Responses

Request samples

cURL

curl -X PATCH https://api.golinks.io/golinks \
  -H "Authorization: Bearer $GOLINKS_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "gid=12130" \
  --data-urlencode "description=Company shared Google Drive folder"

Response samples

Content type

application/json

{"status": "ok",
"gid": 12130,
"cid": 12,
"user": {"uid": 484371,
"first_name": "Test",
"last_name": "User",
"username": "test.user",
"email": "[email protected]",
"user_image_url": "https://www.gravatar.com/avatar/94d093eda664addd6e450d7e9881bcad?s=32&d=identicon&s=200&r=pg"
},
"url": "https://drive.google.com/drive/",
"name": "drive",
"description": "Company shared Google Drive folder",
"tags": [{"tid": 79,
"name": "drive"
}
],
"unlisted": 0,
"private": 0,
"variable_link": 0,
"pinned": 0,
"created_at": 1576577874,
"updated_at": 1600000000,
"aliases": [ ],
"multilinks": [ ],
"geolinks": [ ]
}

Delete a go link

https://api.golinks.io/golinks?gid=12130

Delete an existing go link, including its aliases, tags and multi-link or geo link mappings. Workspaces can restrict deletion to admins; owners can always delete their own private go links.

Authorizations:

ApiTokenOAuth2

query Parameters

gid

required

integer

Example: gid=12130

ID of the go link to delete.

Responses

Request samples

cURL

curl -X DELETE "https://api.golinks.io/golinks?gid=12130" \
  -H "Authorization: Bearer $GOLINKS_TOKEN"

Response samples

200
401
403
422
429

Content type

application/json

{"status": "ok"
}

Retrieve a go link

https://api.golinks.io/golinks/{gid}

Retrieve the details of a single go link by its ID. To look a go link up by name use GET /golinks?name= instead. Private go links are only returned to their owner.

Authorizations:

ApiTokenOAuth2

path Parameters

gid

required

integer

Example: 12130

ID of the go link.

Responses

Request samples

cURL

curl https://api.golinks.io/golinks/12130 \
  -H "Authorization: Bearer $GOLINKS_TOKEN"

Response samples

Content type

application/json

{"gid": 12130,
"cid": 12,
"user": {"uid": 484371,
"first_name": "Test",
"last_name": "User",
"username": "test.user",
"email": "[email protected]",
"user_image_url": "https://www.gravatar.com/avatar/94d093eda664addd6e450d7e9881bcad?s=32&d=identicon&s=200&r=pg"
},
"url": "https://drive.google.com/drive/",
"name": "drive",
"description": "Company shared Google Drive",
"app_domain": "google.com",
"tags": [{"tid": 79,
"name": "drive"
}
],
"aliases": [{"aid": 512,
"gid": 12130,
"name": "gdrive",
"url": "https://drive.google.com/drive/"
}
],
"aliases_total_count": 1,
"collections": [{"collid": 42,
"name": "Onboarding",
"icon": "rocket"
}
],
"collections_count": 1,
"unlisted": 0,
"private": 0,
"variable_link": 0,
"pinned": 0,
"redirect_hits": {"daily": 100,
"weekly": 100,
"monthly": 100,
"alltime": 100
},
"created_at": 1576577874,
"updated_at": 1576577874
}

Create several go links

https://api.golinks.io/golinks_bulk

Create several standard go links in one request. Bulk-created links are always visible to the whole workspace: tags, aliases, multi-links, geo links and the unlisted, private or public flags are not supported here. Names are validated like single go links and the whole request fails if any name is already taken (409) or repeated in the payload (422). The request body must be form-encoded.

The response contains the last go link that was created; retrieve the others with GET /golinks?name=.

Authorizations:

ApiTokenOAuth2

Request Body schema: application/x-www-form-urlencoded
required

required	Array of objects The go links to create. Names must be unique within the request and unused in the workspace.
format	integer Enum: 0 1 `1` strips characters that are not allowed in go link names from every `name`.
hyphens	integer Enum: 0 1 Requires `format=1`. `1` replaces spaces in names with hyphens; `0` removes them.
uid	integer Create the go links on behalf of another active user in your workspace. Defaults to the token owner.

Responses

Request samples

cURL

curl -X POST https://api.golinks.io/golinks_bulk \
  -H "Authorization: Bearer $GOLINKS_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "golinksArray[0][name]=drive" \
  --data-urlencode "golinksArray[0][url]=https://drive.google.com/drive/" \
  --data-urlencode "golinksArray[0][description]=Company shared Google Drive" \
  --data-urlencode "golinksArray[0][create_source]=my-integration" \
  --data-urlencode "golinksArray[1][name]=jira" \
  --data-urlencode "golinksArray[1][url]=https://golinks.atlassian.net/" \
  --data-urlencode "golinksArray[1][description]=Issue tracker" \
  --data-urlencode "golinksArray[1][create_source]=my-integration"

Response samples

Content type

application/json

{"gid": 12131,
"cid": 12,
"user": {"uid": 484371,
"first_name": "Test",
"last_name": "User",
"username": "test.user",
"email": "[email protected]",
"user_image_url": "https://www.gravatar.com/avatar/94d093eda664addd6e450d7e9881bcad?s=32&d=identicon&s=200&r=pg"
},
"url": "https://golinks.atlassian.net/",
"name": "jira",
"description": "Issue tracker",
"tags": [ ],
"unlisted": 0,
"private": 0,
"variable_link": 0,
"pinned": 0,
"created_at": 1576577874,
"updated_at": 1576577874
}

Metrics

The Metrics API returns the daily redirect hits of a go link.

Retrieve the daily redirect hits of a go link

https://api.golinks.io/metrics/{gid}

Retrieve the daily redirect hits of a go link for the last 30 days (or the number of days given by days). The response contains one entry per day, including today, so 30 days produce 31 entries. Days without redirects have 0 hits. Private go links are only available to their owner.

Authorizations:

ApiTokenOAuth2

path Parameters

gid

required

integer

Example: 12130

ID of the go link.

query Parameters

days	integer >= 1 Default: 30 Number of past days to include.

Responses

Request samples

cURL

curl "https://api.golinks.io/metrics/12130?days=30" \
  -H "Authorization: Bearer $GOLINKS_TOKEN"

Response samples

Content type

application/json

{"gid": 12130,
"name": "drive",
"metrics": [{"date": 1609315200,
"hits": 0
},
{"date": 1609401600,
"hits": 1
},
{"date": 1609488000,
"hits": 3
}
]
}

Users

The Users API lets you retrieve information about the users of your workspace. You can search for users by name or email, and filter by access level or status.

List or search users

https://api.golinks.io/users

Retrieve the users of your workspace, sorted by email unless sort is given. Search for a specific user by name, username or email with search (a partial value such as @golinks.io or jane works), and narrow the list down with access-level and status. Invited users who have not joined yet are not returned.

Authorizations:

ApiTokenOAuth2

query Parameters

access-level[]	Array of strings Items Enum: "admin" "moderator" "member" "limited_member" Example: access-level[]=admin Only return users with these access levels. Repeat the parameter with the PHP bracket name (`access-level[]=admin&access-level[]=moderator`) to allow several. A single value can also be sent as `access-level=admin`, or several as a comma separated list (`access-level=admin,moderator`).
limit	integer [ 1 .. 100 ] Default: 50 Number of users per page.
offset	integer >= 0 Default: 0 Number of users to skip.
order	string Default: "desc" Enum: "asc" "desc" Sort direction.
search	string <= 100 characters Example: [email protected] Text to match against first name, last name, full name and email.
sort	string Enum: "name" "created_at" "status" Sort field. When searching without `sort`, results are ordered by relevance.
status	string Enum: "active" "inactive" Only return active or deactivated users.

Responses

Request samples

cURL

curl "https://api.golinks.io/users?search=test.user&access-level[]=admin" \
  -H "Authorization: Bearer $GOLINKS_TOKEN"

Response samples

200
401
403
422
429

Content type

application/json

{"metadata": {"limit": 50,
"offset": 0,
"count": 1,
"total_results": 1,
"links": {"prev": null,
"next": null
},
"provisioned_users": 0
},
"results": [{"uid": 484371,
"cid": 12,
"ualid": 2,
"first_name": "Test",
"last_name": "User",
"username": "test.user",
"email": "[email protected]",
"user_image_url": "https://www.gravatar.com/avatar/94d093eda664addd6e450d7e9881bcad?s=32&d=identicon&s=200&r=pg",
"role": "engineering",
"admin": 1,
"active": 1,
"created_at": 1556320857,
"updated_at": 1556320857,
"lastvisited": 1688000000,
"total_nonprivate_links": 12
}
]
}

Search

The Search API runs the same search as the GoLinks dashboard and returns matching go links, tags, users and collections.

Search go links, tags, users and collections

https://api.golinks.io/search?search-term=drive

Run the same search as the GoLinks dashboard. search-term is matched against go link names, aliases, descriptions, URLs and tags; when smart search is enabled for the workspace, long natural-language terms are rewritten by AI before searching (the term actually used is returned in true-search-term). Use result-type to choose which resource is the primary, paginated result list.

Go links are returned in the dashboard representation (see the schema); limited members receive empty descriptions and URLs.

Authorizations:

ApiTokenOAuth2

query Parameters

app-result-type	string Default: "links" Enum: "links" "tags" Only with `result-type=apps`. Whether app counts are based on go links or tags.
app-search-term	string Only with `result-type=apps`. Additional term to filter the app list.
app[]	Array of strings Only return go links pointing at these app domains (for example `atlassian.net`). Repeat the parameter (`app[]=atlassian.net&app[]=google.com`) for several domains; a single domain can also be sent as `app=atlassian.net`.
collection_department	string Department to filter collection results by.
collid	integer Only return go links in this collection.
exclude_collid	integer Exclude go links in this collection.
filter[]	Array of strings Items Enum: "all" "my_links" "user_links" "locked_links" "public_links" "private_links" "unlisted_links" "favorite_links" "variable_links" "non_variable_links" "multi_links" "non_multi_links" "geo_links" Go link filters. Repeat the parameter with the PHP bracket name (`filter[]=my_links&filter[]=variable_links`) to combine filters; a single filter can also be sent as `filter=my_links`. `user_links` requires the `username[]` parameter. Filters for locked, public, unlisted and private links require the matching plan feature.
include-primary-filter-count	string Enum: "true" "false" Set to `true` to include `primaryFilterTotal`, the number of go links matching only the primary filters.
limit	integer [ 1 .. 100 ] Default: 100 Number of primary results per page.
modified	string Enum: "today" "last_7_days" "last_30_days" "last_90_days" "last_year" Only return go links modified in this period.
offset	integer >= 0 Default: 0
order	string Default: "desc" Enum: "asc" "desc"
pinned-first	string Default: "true" Enum: "true" "false" Only applies when `sort` is set to a value other than `relevance` (the default). Pinned go links are then listed before all other results unless this is set to `false`, in which case they are sorted along with the rest.
result-type	string Default: "all" Enum: "all" "links" "tags" "users" "collections" "apps" Which resource is the primary result. `all` returns go links plus previews of users, tags and collections.
search-term required	string Example: search-term=drive The search term. A leading `go/` is ignored.
sort	string Default: "relevance" Enum: "relevance" "daily" "weekly" "monthly" "alltime" "new" "created_at" "updated_at" "user_recently_used" "name" Sort order of the go link results. `new` is an alias of `created_at`; `user_recently_used` also filters out go links the token owner never used.
tag[]	Array of strings Only return go links that carry these tags. Repeat the parameter (`tag[]=drive&tag[]=docs`) for several tags; a single tag can also be sent as `tag=drive`.
true-search-term	string Search exactly this term and skip the AI rewrite of `search-term`.
username[]	Array of strings Owner username(s) for the `user_links` filter. Repeat the parameter (`username[]=jane&username[]=john`) for several owners; a single owner can also be sent as `username=jane`.

Responses

Request samples

cURL

curl "https://api.golinks.io/search?search-term=drive&result-type=links&limit=20" \
  -H "Authorization: Bearer $GOLINKS_TOKEN"

Response samples

200
401
403
422
429

Content type

application/json

{"type": "search",
"search-term": "drive",
"true-search-term": "drive",
"spelling-suggestion": null,
"spelling-corrected": false,
"total_links": 1,
"total_tags": 1,
"total_users": 0,
"total_collections": 0,
"users": [ ],
"tags": [{"tid": 79,
"name": "drive",
"count": 1
}
],
"collections": [ ],
"results": [{"gid": 12130,
"cid": 12,
"uid": 484371,
"name": "drive",
"url": "https://drive.google.com/drive/",
"description": "Company shared Google Drive",
"app_domain": "google.com",
"unlisted": 0,
"private": 0,
"public": 0,
"pinned": 0,
"locked": 0,
"variable_link": 0,
"multilink": 0,
"multilink_targets": [ ],
"geolink": 0,
"geolinks": [ ],
"tags": [{"tid": 79,
"name": "drive"
}
],
"aliases": [ ],
"collections": [ ],
"collections_count": 0,
"verification_data": null,
"is_favorite": false,
"daily": 100,
"weekly": 100,
"monthly": 100,
"alltime": 100,
"created_at": "2019-12-17 10:17:54",
"updated_at": "2019-12-17 10:17:54",
"firstname": "Test",
"lastname": "User",
"username": "test.user",
"email": "[email protected]",
"user_image_url": "https://www.gravatar.com/avatar/94d093eda664addd6e450d7e9881bcad?s=32&d=identicon&s=200&r=pg"
}
],
"externalDomain": "",
"location": "US",
"metadata": {"limit": 100,
"offset": 0,
"count": 1,
"total_results": 1,
"links": {"prev": null,
"next": null
}
},
"hasRows": 0
}

Audit Log

The Audit Log API exports the workspace audit log (an Enterprise feature). The token owner must be a workspace admin with permission to view the audit log.

List audit log entries

https://api.golinks.io/admin/audit_log

Retrieve the workspace audit log, newest entries first. The audit log is an Enterprise feature and the token owner must be a workspace admin with the view audit log permission. Filter values are the enum case names listed below (for example section=Golinks, event_type=GoLinkCreated).

Authorizations:

ApiTokenOAuth2

query Parameters

event_type	string Enum: "APITokenCreated" "APITokenDeleted" "APITokenUpdated" "APITokenRevoked" "DomainRolesUpdated" "GoLinkCreated" "GoLinkDeleted" "GoLinkLocked" "GoLinkPinned" "GoLinkUnlocked" "GoLinkUnpinned" "GoLinkUpdated" "InviteRevoked" "SetAccessLevel" "SetActiveStatus" "SetAdminStatus" "UserInvited" "UserUpdated" "WebhookCreated" "WebhookDeleted" "WebhookUpdated" "OAuthAppCreated" "OAuthAppDeleted" "OAuthAppUpdated" "WorkspaceSettingsChanged" "SCIMUserCreated" "SCIMUserUpdated" "SCIMUserDeactivated" "SCIMTokenCreated" "SCIMTokenRevoked" "CollectionCreated" "CollectionDeleted" "CollectionUpdated" "TagCreated" "TagDeleted" "TagUpdated" "TagsMerged" "JotCreated" "JotDeleted" "ProvisionedUserRemoved" "CrossProductLoginTokenIssued" Specific event.
export	string Value: "true" Set to `true` to export up to 5000 entries in one response (ignores `limit`).
filter_uid	integer Only return entries caused by this user.
general_type	string Enum: "Added" "Changed" "Removed" Kind of change.
limit	integer [ 1 .. 100 ] Default: 20 Number of entries per page.
offset	integer >= 0 Default: 0
search	string <= 100 characters Text to match against the entry message and event type.
section	string Enum: "Golinks" "UserManagement" "Settings" "DeveloperTools" "SCIM" "Collections" "Tags" "Jots" Product area the entry belongs to.

Responses

Request samples

cURL

curl "https://api.golinks.io/admin/audit_log?section=Golinks&limit=20" \
  -H "Authorization: Bearer $GOLINKS_TOKEN"

Response samples

200
401
403
422
429

Content type

application/json

{"metadata": {"limit": 20,
"offset": 0,
"count": 1,
"total_results": 1,
"links": {"prev": null,
"next": null
}
},
"results": [{"alid": 9001,
"cid": 12,
"uid": 484371,
"email": "[email protected]",
"general_type": "Added",
"section": "Go links",
"event_type": "Go link created",
"api": "/d/api/golinks/index.php",
"method": "POST",
"message": "go/drive created (standard)",
"request_body": null,
"response_body": {"gid": 12130,
"name": "drive"
},
"created_at": 1700000000,
"updated_at": 1700000000
}
]
}

OAuth

Token endpoints for OAuth 2.0 apps registered in Developer Tools › OAuth Apps. See Authentication for the full authorization flow.

Exchange an authorization code or refresh token

https://api.golinks.io/oauth/token

Token endpoint of the OAuth 2.0 Authorization Code flow with PKCE. Send grant_type=authorization_code with the code received on your redirect URI and the code_verifier, or grant_type=refresh_token with a refresh token to rotate the pair. Access tokens are valid for one hour. Refresh tokens are single use: the previous access and refresh tokens are revoked as soon as the new pair is issued, and presenting an already used refresh token revokes every token of the grant.

The endpoint is unauthenticated (apps are public clients) and accepts form-encoded or JSON bodies. It is rate limited to 60 requests per minute per client.

Request Body schema:
application/x-www-form-urlencoded
required

One of

client_id required	string Client ID of the OAuth app.
code required	string Authorization code received on the redirect URI.
code_verifier required	string PKCE verifier whose SHA-256 (base64url) matches the `code_challenge` sent in the authorization request.
grant_type required	string Value: "authorization_code"
redirect_uri required	string <uri> The same `redirect_uri` that was used in the authorization request.

Responses

Request samples

Payload
cURL (authorization code)
cURL (refresh)

Content type

application/x-www-form-urlencoded

No sample

Response samples

Content type

application/json

{"access_token": "3f9c2c4a0b6f4d1e9a8c7b6a5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1",
"scope": "golinks:read golinks:write"
}

Revoke a token

https://api.golinks.io/oauth/revoke

Revoke an access or refresh token (RFC 7009). Revoking a refresh token also revokes the access token issued with it. The endpoint always responds with 200 and an empty JSON object, even when the token is unknown or belongs to another client, so callers cannot probe for valid tokens. It is unauthenticated and accepts form-encoded or JSON bodies.

Request Body schema:
application/x-www-form-urlencoded
required

client_id required	string Client ID of the OAuth app the token belongs to.
token required	string The access or refresh token to revoke. Revoking a refresh token also revokes the access token issued with it.
token_type_hint	string Enum: "access_token" "refresh_token" Optional hint about the token type, per RFC 7009. GoLinks tries the other type when the hinted one does not match.

Responses

Request samples

Payload
cURL

Content type

application/x-www-form-urlencoded

No sample

Response samples

200
405
422
429

Content type

application/json

{ }

GoLinks API Documentation (2.0.0)

Introduction

Authentication

API tokens

Create an access token

How to use your access token

OAuth 2.0

API Overview

Base URL

Request format

Errors

Rate Limiting

Pagination

Timestamps

Support

Go Links

List go links or retrieve a go link by name

Authorizations:

query Parameters

Responses

Request samples

Response samples

Create a go link

Authorizations:

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Request samples

Response samples

Update a go link

Authorizations:

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Request samples

Response samples

Update part of a go link

Authorizations:

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Request samples

Response samples

Delete a go link

Authorizations:

query Parameters

Responses

Request samples

Response samples

Retrieve a go link

Authorizations:

path Parameters

Responses

Request samples

Response samples

Create several go links

Authorizations:

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Request samples

Response samples

Metrics

Retrieve the daily redirect hits of a go link

Authorizations:

path Parameters

query Parameters

Responses

Request samples

Response samples

Users

List or search users

Authorizations:

query Parameters

Responses

Request samples

Response samples

Search

Search go links, tags, users and collections

Authorizations:

query Parameters

Responses

Request samples

Response samples

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema:
application/x-www-form-urlencoded
required

Request Body schema:
application/x-www-form-urlencoded
required