API quickstart

Five steps from zero to a live short link. Every example works with curl and needs nothing but a credential.

1. Pick a credential

You need one of two:

Credential	When to use it
NUXT_SITE_TOKEN	You own the instance. Full access, including configuration.
API key (ink_…)	You are integrating a tool. Limited to the key's role.

For the rest of this guide, export the token you will use:

export INKPAGE_TOKEN="ink_your_api_key_here"

2. Confirm the connection

curl https://your-domain/api/verify \
  -H "Authorization: Bearer $INKPAGE_TOKEN"

A successful response reports the credential, its identity, and the permissions it carries:

{
  "name": "Inkpage Links",
  "url": "https://inkpage.link",
  "authMethod": "api-key",
  "userID": "apikey:3f2a...",
  "userEmail": "apikey:n8n@your-domain",
  "accessEnabled": false,
  "role": "power-user",
  "permissions": ["links:read", "links:write"]
}

authMethod is one of site-token, api-key, session, access-user, or access-service.

If you get 401, the token is missing, malformed, expired, or revoked. If you get 403, the credential is valid but lacks the permission the route requires.

3. Create a short link

curl -X POST https://your-domain/api/link/create \
  -H "Authorization: Bearer $INKPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/somewhere", "slug": "first-link" }'

The route answers 201 with the stored link and the resolved short URL:

{
  "link": { "slug": "first-link", "url": "https://example.com/somewhere", "createdAt": 1798761600 },
  "shortLink": "https://your-domain/first-link"
}

The short link is now https://your-domain/first-link.

Storage must be ready

If you receive 423 ("storage not ready"), open Dashboard → Links once in the browser. The app initializes its storage on first visit. See storage setup.

4. Read it back

curl "https://your-domain/api/link/query?slug=first-link" \
  -H "Authorization: Bearer $INKPAGE_TOKEN"

The response carries the full configuration of the link, so you can confirm every field you set — password, expiration, tags, geo rules, preview metadata.

5. List and paginate

curl "https://your-domain/api/link/list?limit=20" \
  -H "Authorization: Bearer $INKPAGE_TOKEN"

Pass the returned cursor to fetch the next page, and stop when list_complete is true. Cursors are opaque — never construct one yourself.

Next steps

• REST API — every endpoint, error codes, and copy-paste recipes.
• Interactive reference — generated from your instance.
• Integrations — MCP server for AI clients.
• Subdomains — serve a link from a custom domain.