Agent Skills: shortio

Troubleshooting

If requests fail, run zero doctor check-connector --env-name SHORTIO_TOKEN or zero doctor check-connector --url https://api.short.io/links --method GET

How to Use

All examples below assume you have SHORTIO_TOKEN and SHORTIO_DOMAIN set.

Base URL: https://api.short.io

1. Create a Short Link

Create a new short link with auto-generated slug:

Write to /tmp/shortio_request.json:

{
  "domain": "<your-domain-name>",
  "originalURL": "https://example.com/very/long/url/here"
}

Then run:

curl -s -X POST "https://api.short.io/links" --header "Authorization: $SHORTIO_TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" -d @/tmp/shortio_request.json | jq '{shortURL, originalURL, path, idString}'

2. Create with Custom Slug

Create a short link with a custom path/slug:

Write to /tmp/shortio_request.json:

{
  "domain": "<your-domain-name>",
  "originalURL": "https://example.com/product/12345",
  "path": "my-custom-slug"
}

Then run:

curl -s -X POST "https://api.short.io/links" --header "Authorization: $SHORTIO_TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" -d @/tmp/shortio_request.json | jq '{shortURL, originalURL, path, idString}'

3. Create with TTL (Expiration)

Create a link that expires after a specified time (in ISO 8601 format):

Write to /tmp/shortio_request.json:

{
  "domain": "<your-domain-name>",
  "originalURL": "https://example.com/temporary-offer",
  "ttl": "2026-12-31T23:59:59Z"
}

Then run:

curl -s -X POST "https://api.short.io/links" --header "Authorization: $SHORTIO_TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" -d @/tmp/shortio_request.json | jq '{shortURL, originalURL, ttl}'

4. Get Link Info by Path

Get details of a short link using domain and path:

curl -s -X GET "https://api.short.io/links/expand?domain=$SHORTIO_DOMAIN&path=my-custom-slug" --header "Authorization: $SHORTIO_TOKEN" --header "Accept: application/json" | jq '{originalURL, shortURL, path, idString, createdAt, cloaking}'

5. Get Link Info by ID

Get details of a short link using its ID:

LINK_ID="lnk_abc123xyz"

curl -s -X GET "https://api.short.io/links/${LINK_ID}" --header "Authorization: $SHORTIO_TOKEN" --header "Accept: application/json" | jq '{originalURL, shortURL, path, idString, createdAt}'

6. List All Links

Get a list of links for a domain (max 150 per request):

curl -s -X GET "https://api.short.io/api/links?domain_id=$SHORTIO_DOMAIN_ID&limit=20" --header "Authorization: $SHORTIO_TOKEN" --header "Accept: application/json" | jq '{count, links: [.links[] | {shortURL, originalURL, path, idString}]}'

7. Update a Link

Update an existing link's path, original URL, or other properties:

LINK_ID="lnk_abc123xyz"

Write to /tmp/shortio_request.json:

{
  "path": "new-custom-slug",
  "originalURL": "https://example.com/new-destination"
}

Then run:

curl -s -X POST "https://api.short.io/links/${LINK_ID}" --header "Authorization: $SHORTIO_TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" -d @/tmp/shortio_request.json | jq '{shortURL, originalURL, path, idString}'

8. Delete a Link

Delete a short link by ID:

LINK_ID="lnk_abc123xyz"

curl -s -X DELETE "https://api.short.io/links/${LINK_ID}" --header "Authorization: $SHORTIO_TOKEN" --header "Accept: application/json" | jq '{success, idString}'

9. List Domains

Get all domains associated with your account:

curl -s -X GET "https://api.short.io/api/domains" --header "Authorization: $SHORTIO_TOKEN" --header "Accept: application/json" | jq '.[] | {id, hostname, state, linkType}'

10. Get Link Click Statistics

Get click counts for specific links:

curl -s -X GET "https://api.short.io/domains/$SHORTIO_DOMAIN_ID/link_clicks?link_ids=${LINK_ID}" --header "Authorization: $SHORTIO_TOKEN" --header "Accept: application/json" | jq '{linkId: .linkId, clicks}'

Create Link Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | domain | string | Yes | Your branded domain | | originalURL | string | Yes | The destination URL | | path | string | No | Custom slug (auto-generated if not provided) | | title | string | No | Link title for organization | | ttl | string | No | Expiration date (ISO 8601 format) | | allowDuplicates | boolean | No | Allow creating duplicate links (default: false) | | cloaking | boolean | No | Enable URL cloaking | | password | string | No | Password protect the link | | expiresAt | string | No | Redirect URL when link expires | | tags | array | No | Tags for categorization |

Response Fields

| Field | Description | |-------|-------------| | shortURL | The generated short URL | | secureShortURL | HTTPS version of short URL | | originalURL | The destination URL | | path | The slug/path of the short link | | idString | Unique link ID (use for updates/deletes) | | DomainId | Domain ID | | createdAt | Creation timestamp | | cloaking | Whether cloaking is enabled | | hasPassword | Whether link is password protected |

Guidelines

1. Save the idString: Always store the idString from the response - you'll need it to update or delete links
2. Use TTL for temporary links: Set expiration for promotional or time-sensitive links
3. Limit parameter: When listing links, max limit is 150 per request; use pagination for more
4. Custom domains: Configure DNS properly before using custom domains
5. Avoid duplicates: Set allowDuplicates: false to prevent creating multiple short links for the same URL
6. Check rate limits: API has rate limiting; implement retries with backoff for high-volume usage