Shark Track API

Create and manage short links, variants, projects and analytics over plain HTTP. Everything the dashboard does, the API does.

Quickstart

Create a key in the dashboard under Settings › API keys. It is shown once. Store it in an environment variable rather than pasting it into a file or a chat.

# Create a link. The utm_source is lifted out of the URL automatically.
curl -sX POST https://app.shrk.in/v1/links \
  -H "Authorization: Bearer $SHARK_TRACK_KEY" \
  -H "content-type: application/json" \
  -d '{"destination":"https://example.com/sale?utm_source=newsletter"}'

{
  "id": "lnk_8Kq2mXpR",
  "shortUrl": "https://shrk.in/aB3xY9",
  "destination": "https://example.com/sale",
  "params": { "utm_source": "newsletter" }
}

Authentication

Send the key as a bearer token on every request. The base URL is https://app.shrk.in/v1.

Authorization: Bearer stk_live_...

Keys cannot manage other keys, and cannot sign in. A key inherits the powers of the account that created it, so only a superuser key can set or rename a custom slug.

Concepts worth knowing

A variant is a second address to the same destination, like shrk.in/sale/email, with its own parameters layered over the link's. A project is a folder; a link belongs to at most one, while tags are many per link.

All timestamps are epoch milliseconds. clickCount counts humans; bot hits are counted separately in botCount and excluded from analytics unless you pass bots=1.

Errors

Every failure returns the same shape. Branch on code, never on the message, which may be reworded.

{
  "error": {
    "code": "delete_requires_dashboard",
    "message": "This link has 143 recorded clicks. Sign in to delete it, or archive it instead.",
    "field": null
  }
}

Rate limits

600 requests per minute per key. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining, and a 429 carries Retry-After in seconds.

Endpoints

Paths are relative to https://app.shrk.in/v1. The OpenAPI 3.1 spec has full request and response schemas.

Deleting links

Archive instead. The link keeps working and keeps its history, it just leaves the list.

curl -sX PATCH https://app.shrk.in/v1/links/lnk_123 \
  -H "Authorization: Bearer $SHARK_TRACK_KEY" \
  -H "content-type: application/json" \
  -d '{"status":"archived"}'

Use with Claude

No MCP server needed. Claude can call this API directly with curl, and read the spec to work out how.

1. Put the key in the environment

export SHARK_TRACK_KEY="stk_live_..."

Never paste the key into a chat message or commit it. Claude reads it from the environment when it runs a command.

2. Point Claude at the spec

The Shark Track API is documented at https://docs.shrk.in/llms.txt
and the full spec is at https://docs.shrk.in/openapi.json
My key is in $SHARK_TRACK_KEY. Create short links for these five URLs
and put them in a project called Q4 launch.

llms.txt is the compact version and fits comfortably in context. Use the OpenAPI spec when exact schemas matter.

3. Give it a read key unless it needs to write

Useful things to ask for: a weekly summary of which links got clicks and from where, a variant per channel across a set of links, a CSV export pulled into a spreadsheet, or a batch of links built from a list of URLs.