Go Links API Documentation

Introduction

GoLinks API - Manage your Go Links, tags, and permissions programmatically.

Base URL: http://localhost

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_SANCTUM_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your API token by click the user profile dropdown in the upper right-hand corner, selecting API Access, and generating a new personal access token.

Links

APIs for managing Go Links

Get Links

GET

http://localhost

/api/v2/links

requires authentication

Retrieve all links accessible to the authenticated user. This includes links owned by the user and links shared with them.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Page number for pagination.

Example:

per_page

integer

Number of results per page (max 100).

Example:

filter[owned]

boolean

Filter to only show owned links.

Example:

true

filter[shared]

boolean

Filter to only show shared links.

Example:

false

filter[enabled]

boolean

Filter by enabled status.

Example:

true

filter[tag]

string

Filter by tag label.

Example:

important

filter[search]

string

Search in link strings and target URLs.

Example:

example

sort

string

Sort field (string, target_url, created_at, hit_count). Default: created_at.

Example:

hit_count

order

string

Sort order (asc, desc). Default: desc.

Example:

desc

Body Parameters

per_page

integer

Must be at least 1. Must not be greater than 100.

Example:

filter

object

owned

boolean

Example:

true

shared

boolean

Example:

false

enabled

boolean

Example:

false

tag

string

Example:

architecto

string

Example:

architecto

sort

string

order

string

Response Fields

integer

The unique link identifier (read-only).

string

The short link code (read-only).

target_url

string

The destination URL (writable).

enabled

boolean

Whether the link is enabled (writable).

hit_count

integer

Total number of times the link has been accessed (read-only).

http_status_code

integer

HTTP status code from last health check (read-only).

last_status_check_at

string

Timestamp of last status check (read-only).

exclude_from_status_check

boolean

Whether to exclude from automated health checks (writable, staff only).

created_at

string

Creation timestamp (read-only).

updated_at

string

Last modification timestamp (read-only).

owner

object

The link owner details (read-only).

tags

string[]

Associated tags (managed via separate endpoints).

is_owner

boolean

Whether the authenticated user is the owner (read-only).

is_shared

boolean

Whether the link is shared with the user (read-only).

Auth

Bearer

Headers

Query Parameters

Body

{ "per_page": 1, "filter": { "owned": true, "shared": false, "enabled": false, "tag": "architecto", "search": "architecto" }, "sort": null, "order": null }

Received response

Example request:

curl --request GET \
    --get "http://localhost/api/v2/links?page=1&per_page=15&filter%5Bowned%5D=1&filter%5Bshared%5D=&filter%5Benabled%5D=1&filter%5Btag%5D=important&filter%5Bsearch%5D=example&sort=hit_count&order=desc" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 1,
    \"filter\": {
        \"owned\": true,
        \"shared\": false,
        \"enabled\": false,
        \"tag\": \"architecto\",
        \"search\": \"architecto\"
    }
}"

Example response:

{
    "data": [
        {
            "id": 1,
            "string": "example",
            "target_url": "https://example.com",
            "enabled": true,
            "hit_count": 42,
            "http_status_code": 200,
            "last_status_check_at": "2025-11-21 10:30:00",
            "exclude_from_status_check": false,
            "created_at": "2025-11-01T12:00:00.000000Z",
            "updated_at": "2025-11-21T10:30:00.000000Z",
            "owner": {
                "id": 1,
                "name": "John Doe",
                "unity_id": "jdoe"
            },
            "tags": [
                {
                    "id": 1,
                    "label": "important",
                    "name": "important"
                }
            ],
            "is_owner": true,
            "is_shared": false
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 42,
        "last_page": 3
    }
}

Create Link

POST

http://localhost

/api/v2/links

requires authentication

Create a new Go Link. If no custom string is provided, a random 7-character string will be generated. Users need the appropriate permissions to create random or custom links.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

string

Optional custom link string (requires "create custom links" permission). Must be lowercase alphanumeric with hyphens, underscores, or periods.

Example:

my-link

target_url

string

required

The destination URL (must include http:// or https://).

Example:

https://example.com

enabled

boolean

Whether the link is enabled. Default: true.

Example:

true

exclude_from_status_check

boolean

Exclude from automated status checks (staff only). Default: false.

Example:

false

tag_id

integer

Optional tag ID to attach to the link.

Example:

share_with

string

Optional Unity ID or Google Group email to share with.

Example:

jdoe

Response Fields

integer

The unique link identifier (read-only).

string

The short link code (read-only after creation).

target_url

string

The destination URL (writable).

enabled

boolean

Whether the link is enabled (writable).

hit_count

integer

Total number of times the link has been accessed (read-only).

http_status_code

integer

HTTP status code from last health check (read-only).

last_status_check_at

string

Timestamp of last status check (read-only).

exclude_from_status_check

boolean

Whether to exclude from automated health checks (writable, staff only).

created_at

string

Creation timestamp (read-only).

updated_at

string

Last modification timestamp (read-only).

owner

object

The link owner details (read-only).

tags

string[]

Associated tags (managed via separate endpoints).

Auth

Bearer

Headers

Body

{ "string": "my-link", "target_url": "https:\/\/example.com", "enabled": true, "exclude_from_status_check": false, "tag_id": 1, "share_with": "jdoe" }

Received response

Example request:

curl --request POST \
    "http://localhost/api/v2/links" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"string\": \"my-link\",
    \"target_url\": \"https:\\/\\/example.com\",
    \"enabled\": true,
    \"exclude_from_status_check\": false,
    \"tag_id\": 1,
    \"share_with\": \"jdoe\"
}"

Example response:

{
    "id": 1,
    "string": "my-link",
    "target_url": "https://example.com",
    "enabled": true,
    "hit_count": 0,
    "http_status_code": null,
    "last_status_check_at": null,
    "exclude_from_status_check": false,
    "created_at": "2025-11-21T12:00:00.000000Z",
    "updated_at": "2025-11-21T12:00:00.000000Z",
    "owner": {
        "id": 1,
        "name": "John Doe",
        "unity_id": "jdoe"
    },
    "tags": [
        {
            "id": 1,
            "label": "important",
            "name": "important"
        }
    ]
}

Bulk Update Links

PATCH

http://localhost

/api/v2/links/bulk-update

requires authentication

Update the target URL for multiple links in a single request. Each link is independently authorized — you must have manage permissions for each link. Links you cannot manage or that do not exist will be returned in the errors array.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

links

string[]

required

Array of link updates (max 50).

Auth

Bearer

Headers

Body

{ "links": { "string": "my-link", "target_url": "https:\/\/example.com\/new" } }

Received response

Example request:

curl --request PATCH \
    "http://localhost/api/v2/links/bulk-update" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"links\": [
        {
            \"string\": \"my-link\",
            \"target_url\": \"https:\\/\\/example.com\\/new\"
        }
    ]
}"

Example response:

{
    "updated": [
        {
            "string": "my-link",
            "target_url": "https://example.com/new"
        }
    ],
    "errors": [
        {
            "string": "bad-link",
            "error": "Link not found"
        },
        {
            "string": "other-link",
            "error": "Unauthorized"
        }
    ]
}

Get Link

GET

http://localhost

/api/v2/links/{string}

requires authentication

Retrieve a specific link by its string identifier.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The link string.

Example:

my-link

Response Fields

integer

The unique link identifier (read-only).

string

The short link code (read-only).

target_url

string

The destination URL (writable).

enabled

boolean

Whether the link is enabled (writable).

hit_count

integer

Total number of times the link has been accessed (read-only).

http_status_code

integer

HTTP status code from last health check (read-only).

last_status_check_at

string

Timestamp of last status check (read-only).

exclude_from_status_check

boolean

Whether to exclude from automated health checks (writable, staff only).

created_at

string

Creation timestamp (read-only).

updated_at

string

Last modification timestamp (read-only).

owner

object

The link owner details (read-only).

tags

string[]

Associated tags (managed via separate endpoints).

rules

string[]

Access control rules (read-only, no API endpoint to modify).

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "http://localhost/api/v2/links/my-link" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "id": 1,
    "string": "my-link",
    "target_url": "https://example.com",
    "enabled": true,
    "hit_count": 42,
    "http_status_code": 200,
    "last_status_check_at": "2025-11-21 10:30:00",
    "exclude_from_status_check": false,
    "created_at": "2025-11-01T12:00:00.000000Z",
    "updated_at": "2025-11-21T10:30:00.000000Z",
    "owner": {
        "id": 1,
        "name": "John Doe",
        "unity_id": "jdoe"
    },
    "tags": [
        {
            "id": 1,
            "label": "important",
            "name": "important"
        }
    ],
    "rules": [
        {
            "id": 1,
            "value": "admins@ncsu.edu",
            "created_at": "2025-11-01T12:00:00.000000Z",
            "updated_at": "2025-11-01T12:00:00.000000Z"
        },
        {
            "id": 2,
            "value": "jsmith@ncsu.edu",
            "created_at": "2025-11-02T14:30:00.000000Z",
            "updated_at": "2025-11-02T14:30:00.000000Z"
        }
    ]
}

Update Link

PATCH

http://localhost

/api/v2/links/{string}

requires authentication

Update an existing link. You must be the owner or have manage permissions.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The link string.

Example:

my-link

Body Parameters

target_url

string

The destination URL.

Example:

https://newexample.com

enabled

boolean

Whether the link is enabled.

Example:

false

exclude_from_status_check

boolean

Exclude from status checks (staff only).

Example:

true

Response Fields

integer

The unique link identifier (read-only).

string

The short link code (read-only).

target_url

string

The destination URL (writable).

enabled

boolean

Whether the link is enabled (writable).

hit_count

integer

Total number of times the link has been accessed (read-only).

http_status_code

integer

HTTP status code from last health check (read-only).

last_status_check_at

string

Timestamp of last status check (read-only).

exclude_from_status_check

boolean

Whether to exclude from automated health checks (writable, staff only).

created_at

string

Creation timestamp (read-only).

updated_at

string

Last modification timestamp (read-only).

owner

object

The link owner details (read-only).

tags

string[]

Associated tags (managed via separate endpoints).

Auth

Bearer

Headers

URL Parameters

Body

{ "target_url": "https:\/\/newexample.com", "enabled": false, "exclude_from_status_check": true }

Received response

Example request:

curl --request PATCH \
    "http://localhost/api/v2/links/my-link" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"target_url\": \"https:\\/\\/newexample.com\",
    \"enabled\": false,
    \"exclude_from_status_check\": true
}"

Example response:

{
    "id": 1,
    "string": "my-link",
    "target_url": "https://newexample.com",
    "enabled": false,
    "hit_count": 42,
    "http_status_code": 200,
    "last_status_check_at": "2025-11-21 10:30:00",
    "exclude_from_status_check": true,
    "created_at": "2025-11-01T12:00:00.000000Z",
    "updated_at": "2025-11-21T12:30:00.000000Z",
    "owner": {
        "id": 1,
        "name": "John Doe",
        "unity_id": "jdoe"
    },
    "tags": []
}

Delete Link

DELETE

http://localhost

/api/v2/links/{string}

requires authentication

Delete a link. You must be the owner of the link to delete it.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The link string.

Example:

my-link

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "http://localhost/api/v2/links/my-link" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "message": "Link deleted successfully."
}

Transfer Link

POST

http://localhost

/api/v2/links/{string}/transfer

requires authentication

Transfer ownership of a link to another user. You must be the owner of the link.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The link string.

Example:

my-link

Body Parameters

new_owner_unity_id

string

required

The Unity ID of the new owner.

Example:

jsmith

Auth

Bearer

Headers

URL Parameters

Body

{ "new_owner_unity_id": "jsmith" }

Received response

Example request:

curl --request POST \
    "http://localhost/api/v2/links/my-link/transfer" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"new_owner_unity_id\": \"jsmith\"
}"

Example response:

{
    "message": "Link transferred successfully.",
    "link": {
        "id": 1,
        "string": "my-link",
        "target_url": "https://example.com",
        "owner": {
            "id": 2,
            "name": "Jane Smith",
            "unity_id": "jsmith"
        }
    }
}

Attach Tag to Link

POST

http://localhost

/api/v2/links/{string}/tags

requires authentication

Attach a tag to a link. You must have manage permissions for both the link and the tag.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The link string.

Example:

my-link

Body Parameters

tag_id

integer

required

The tag ID to attach.

Example:

Auth

Bearer

Headers

URL Parameters

Body

{ "tag_id": 1 }

Received response

Example request:

curl --request POST \
    "http://localhost/api/v2/links/my-link/tags" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"tag_id\": 1
}"

Example response:

{
    "message": "Tag attached successfully.",
    "link": {
        "id": 1,
        "string": "my-link",
        "tags": [
            {
                "id": 1,
                "label": "important",
                "name": "important"
            }
        ]
    }
}

Detach Tag from Link

DELETE

http://localhost

/api/v2/links/{string}/tags/{tag}

requires authentication

Remove a tag from a link. You must have manage permissions for the link.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The link string.

Example:

my-link

tag

integer

required

The tag ID to detach.

Example:

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "http://localhost/api/v2/links/my-link/tags/1" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "message": "Tag detached successfully.",
    "link": {
        "id": 1,
        "string": "my-link",
        "tags": []
    }
}

Tags

APIs for managing tags

Get Tags

GET

http://localhost

/api/v2/tags

requires authentication

Retrieve all tags owned by the authenticated user.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

page

integer

Page number for pagination.

Example:

per_page

integer

Number of results per page (max 100).

Example:

filter[search]

string

Search in tag labels.

Example:

project

sort

string

Sort field (label, created_at, updated_at). Default: label.

Example:

label

order

string

Sort order (asc, desc). Default: asc.

Example:

asc

include_counts

boolean

Include link counts and hit totals for each tag. Default: false.

Example:

true

Body Parameters

per_page

integer

Must be at least 1. Must not be greater than 100.

Example:

filter

object

sort

string

order

string

include_counts

boolean

Example:

true

Response Fields

integer

The unique tag identifier (read-only).

label

string

The tag display label (writable).

name

string

The tag slug name, auto-generated from label (read-only).

created_at

string

Creation timestamp (read-only).

updated_at

string

Last modification timestamp (read-only).

links_count

integer

Number of links tagged with this tag (read-only, only when include_counts=true).

hits

integer

Total hits across all links with this tag (read-only, only when include_counts=true).

Auth

Bearer

Headers

Query Parameters

Body

{ "per_page": 1, "filter": { "search": "architecto" }, "sort": null, "order": null, "include_counts": true }

Received response

Example request:

curl --request GET \
    --get "http://localhost/api/v2/tags?page=1&per_page=15&filter%5Bsearch%5D=project&sort=label&order=asc&include_counts=1" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 1,
    \"filter\": {
        \"search\": \"architecto\"
    },
    \"include_counts\": true
}"

Example response:

{
    "data": [
        {
            "id": 1,
            "label": "important",
            "name": "important",
            "created_at": "2025-11-01T12:00:00.000000Z",
            "updated_at": "2025-11-01T12:00:00.000000Z",
            "links_count": 5,
            "hits": 142
        },
        {
            "id": 2,
            "label": "project-alpha",
            "name": "project-alpha",
            "created_at": "2025-11-02T10:00:00.000000Z",
            "updated_at": "2025-11-02T10:00:00.000000Z",
            "links_count": 12,
            "hits": 847
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 2,
        "last_page": 1
    }
}

Create Tag

POST

http://localhost

/api/v2/tags

requires authentication

Create a new tag for organizing your links.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

label

string

required

The tag label (will be slugified).

Example:

My Project

Response Fields

integer

The unique tag identifier (read-only).

label

string

The tag display label (writable).

name

string

The tag slug name, auto-generated from label (read-only).

user_id

integer

The tag owner's user ID (read-only).

created_at

string

Creation timestamp (read-only).

updated_at

string

Last modification timestamp (read-only).

Auth

Bearer

Headers

Body

{ "label": "My Project" }

Received response

Example request:

curl --request POST \
    "http://localhost/api/v2/tags" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"label\": \"My Project\"
}"

Example response:

{
    "id": 1,
    "label": "My Project",
    "name": "my-project",
    "user_id": 1,
    "created_at": "2025-11-21T12:00:00.000000Z",
    "updated_at": "2025-11-21T12:00:00.000000Z"
}

Get Tag

GET

http://localhost

/api/v2/tags/{id}

requires authentication

Retrieve a specific tag by ID.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The ID of the tag.

Example:

architecto

tag

integer

required

The tag ID.

Example:

Query Parameters

include_links

boolean

Include all links with this tag. Default: false.

Example:

true

Response Fields

integer

The unique tag identifier (read-only).

label

string

The tag display label (writable).

name

string

The tag slug name, auto-generated from label (read-only).

user_id

integer

The tag owner's user ID (read-only).

created_at

string

Creation timestamp (read-only).

updated_at

string

Last modification timestamp (read-only).

links_count

integer

Number of links tagged with this tag (read-only).

hits

integer

Total hits across all links with this tag (read-only).

links

string[]

Associated links (read-only, only when include_links=true).

Auth

Bearer

Headers

URL Parameters

Query Parameters

Received response

Example request:

curl --request GET \
    --get "http://localhost/api/v2/tags/architecto?include_links=1" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "id": 1,
    "label": "important",
    "name": "important",
    "user_id": 1,
    "created_at": "2025-11-01T12:00:00.000000Z",
    "updated_at": "2025-11-01T12:00:00.000000Z",
    "links_count": 5,
    "hits": 142,
    "links": [
        {
            "id": 1,
            "string": "example",
            "target_url": "https://example.com",
            "enabled": true
        }
    ]
}

Update Tag

PATCH

http://localhost

/api/v2/tags/{id}

requires authentication

Update a tag's label. You must be the owner of the tag.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The ID of the tag.

Example:

architecto

tag

integer

required

The tag ID.

Example:

Body Parameters

label

string

required

The new tag label.

Example:

Updated Project

Response Fields

integer

The unique tag identifier (read-only).

label

string

The tag display label (writable).

name

string

The tag slug name, auto-generated from label (read-only).

user_id

integer

The tag owner's user ID (read-only).

created_at

string

Creation timestamp (read-only).

updated_at

string

Last modification timestamp (read-only).

Auth

Bearer

Headers

URL Parameters

Body

{ "label": "Updated Project" }

Received response

Example request:

curl --request PATCH \
    "http://localhost/api/v2/tags/architecto" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"label\": \"Updated Project\"
}"

Example response:

{
    "id": 1,
    "label": "Updated Project",
    "name": "updated-project",
    "user_id": 1,
    "created_at": "2025-11-01T12:00:00.000000Z",
    "updated_at": "2025-11-21T12:30:00.000000Z"
}

Delete Tag

DELETE

http://localhost

/api/v2/tags/{id}

requires authentication

Delete a tag. This will automatically detach the tag from all associated links. You must be the owner of the tag.

Headers

Authorization

Example:

Bearer {YOUR_SANCTUM_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The ID of the tag.

Example:

architecto

tag

integer

required

The tag ID.

Example:

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "http://localhost/api/v2/tags/architecto" \
    --header "Authorization: Bearer {YOUR_SANCTUM_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "message": "Tag deleted successfully. The tag was removed from 5 link(s)."
}