GoLinks API

Welcome to the GoLinks API! You can use this API to access our endpoints, such as the Golinks API to create golinks that you and everyone on your team can access. To access our API, you need to be on the GoLinks Enterprise plan. You can upgrade to the Enterprise plan by visiting the [billing page](https://www.golinks.io/billing.php). If you have any questions about the Enterprise plan, you can reach out to the [Sales team](https://www.golinks.io/sales.php). # Authentication The GoLinks API uses access tokens to authenticate requests. The access token must be included in the **Authorization header** of your request. Any user on the Enterprise plan can create and revoke a token. Non-admins can only view and access their own tokens while admins can view and access all the tokens from their organization. Since any user can create a token, do not share your token with other users or include them in publicly accessible areas such as GitHub. If your token gets compromised, you can revoke that token and create a new one. ## Create an Access Token To create an access token, sign in to your GoLinks account and go to the [“Developers”](https://www.golinks.io/settings.php#developers) tab in the "Settings" page. In the “API Tokens” panel, click on “Manage” and then click the “Create token” button. Enter a token name and click on the “Create token” button. Once the token gets created, you will be able to copy the token to your clipboard. You should now see the new token information in the table. You are able to view the raw token anytime you need to, as well as edit the token name and revoke the token. ## How to use your Access Token Once you have created your access token, you can use it to make requests to the API. Requests are authenticated using [HTTP Bearer Authentication](https://tools.ietf.org/html/rfc6750). You must provide the access token in the Authorization header: ``` Authorization: Bearer {ACCESS_TOKEN} ``` If you do not provide an access token or your access token is no longer active, you will receive an error message with a **401 status code**. ``` { "error": { "message": "The API token is not valid or is deactivated.", "code": 401, "type": "not_authorized" } } ``` # API Overview The GoLinks API is REST-based and uses standard HTTP verbs and status codes. The API accepts [form-encoded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request bodies and returns JSON-encoded responses. All requests should be made over SSL. ## Base URL The base URL to access the GoLinks API is [https://api.golinks.io](https://api.golinks.io). For example, to access the _golinks_ endpoint, just add the endpoint to the base URL: [https://api.golinks.io/golinks](https://api.golinks.io/golinks). ## Errors All responses from the API will include a standard HTTP successful or error status code. The successful status codes are as follows: | HTTP Status Code | Description | | --- | --- | | 200 OK | The request was successful. | | 201 Created | The resource has been successfully created. | For errors, we include extra information as to why the request was not successful. The error response body will have the following format: ``` { "error": { "message": "Descriptive information about the error", "code": "HTTP error code", "type": "Type of error returned" } } ``` For example, if you try to create a golink that already exists, you will get the following error response: ``` { "error": { "message": "The golink go/git already exists. Please use another name for the golink.", "code": 409, "type": "conflict" } } ``` The error status codes, along with their error types, are as follows: | HTTP Status Code | Error Type | Description | | --- | --- | --- | | 400 Bad Request | bad_request | The request cannot be accepted. Might be because the request body is empty when it shouldn’t be. | | 401 Unauthorized | not_authorized | The access token provided is invalid or deactivated. | | 409 Conflict | conflict | The request conflicts with an existing resource. For example, if creating a golink with an existing name, this error will be returned. | | 422 Unprocessable Entity | missing_field or invalid_request | The contents of the request contains errors, such as required fields that are missing or validation errors. | | 429 Too Many Requests | rate_limit_exceeded | The rate limit has been exceeded. You have to wait a short time before trying again. | | 500 Internal Server Error | internal_server_error | Something went wrong with the GoLinks API. | ## Rate Limiting A rate limit is enforced for every endpoint and is based on the user's IP address. We currently allow 100 writes per minute and 150 reads per minute. If you exceed the rate limit, you will receive a **429 status code** with the following error body: ``` { "error": { "message": "API rate limit exceeded. Please try again in 60 seconds.", "code": 429, "type": "rate_limit_exceeded" } } ``` Every request contains information about the rate limit in the HTTP response headers. | HTTP Header | Description | | --- | --- | | **RateLimit-Limit** | The maximum number of requests allowed per minute for the endpoint. | | **RateLimit-Remaining** | The number of requests remaining for the current rate limit window. | | **Retry-After** | The number of seconds to wait until the rate limit window resets. This header will only be sent if the rate limit has been exceeded. | ## Pagination All the endpoints that return a list come with a **metadata** object that contains pagination information. We return a default of 50 results per page and use the **limit** and **offset** parameters to determine the number of results to return and the number of results to skip. You can fetch the next set of results through the URL that is provided in _metadata.links.next_. If there are no more results, then the value will be **null**. The metadata object will include the following parameters. The dot notation denotes a child attribute. | Pagination Parameters | Description | | --- | --- | | limit | The limit on the number of results to return, between 1 and 100. Defaults to 50 results. | | offset | The number of results to skip. Defaults to 0. | | count | The number of results returned in the current page. | | total_results | The total number of results found. | | links.next | The URL link to the next set of results. If there are no more results, this will be **null**. | | links.prev | The URL link to the previous set of results. If there are no more results, this will be **null**. | # Setup for Postman If you will be running the following requests in Postman, you can add your **Access token** to the **Pre-request Script** or create a new environment variable named **token** and set the value to be your access token. ``` // Add your access token below postman.setEnvironmentVariable("token", ""); ``` # Support If you have any questions about the API or are running into errors, please reach out to [[email protected]](https://mail.google.com/mail/u/0/?view=cm&fs=1&tf=1&source=mailto&[email protected]).