API Reference

The iNNkie API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, and returns JSON-encoded responses.

Authentication

Authenticate your requests by including your secret API key in the x-api-key header. You can manage your keys in the Developer Studio.

curl https://api.innkie.com/api/v1/links \
  -H "x-api-key: YOUR_WORKSPACE_KEY"

Links

Create a Short Link

POST /links

Creates a new shortened URL within the workspace associated with your API key.

Parameters

urlstring / required

customAliasstring / optional

tagsstring[] / optional

Request Body

{
  "url": "https://google.com",
  "customAlias": "marketing-campaign",
  "tags": ["growth", "summer24"]
}

List Workspace Links

GET /links/workspace/:id

Retrieve all short links belonging to a specific workspace.

Update a Link

PUT /links/:shortCode

Update the destination URL or metadata of an existing short link.

Workspaces

Workspaces are the top-level containers for all iNNkie resources. They manage branding, API keys, and team members.

List My Workspaces

GET /workspaces

Returns a list of all workspaces you have access to, including your personal workspace.

Create Workspace

POST /workspaces

Creates a new professional/team workspace.

Analytics

Access real-time click tracking and visitor data for your shortened links and entire workspaces.

Link Clicks

GET /analytics/:code/clicks

Returns time-series click data for a specific short link. Query parameter ?days=30 supported.

Workspace Overview

GET /analytics/workspace/:id

Retrieve aggregated performance metrics for all links within a workspace.

Webhooks Overview

iNNkie can notify your application when certain events happen in your workspace. Webhooks are sent as POST requests with a JSON payload.

Supported Events

link.created - Fired when a new short link is generated.
link.clicked - Fired every time a short link is visited.

Signature Verification

To ensure that a webhook request was actually sent by iNNkie, we include an X-Innkie-Signature header in every request.

Verification Steps

1. Capture the raw JSON request body.

2. Generate an HMAC SHA256 hash using your webhook secret as the key and the raw body as the message.

3. Compare the resulting hex digest with the value in the header.

Node.js Example

const crypto = require('crypto');

function verify(rawBody, secret, signature) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
    
  return hash === signature;
}