Developer Docs

API Reference

A REST API designed for AI agents, Copilot plugins, and automation workflows. Create, retrieve, update, and share short links under a user’s identity using API key authentication.

Endpoints at a Glance

Base URL: https://links.inworksllc.com

Method	Path	Description	Auth
GET	`/api/ai/links`	List the caller’s links and shared org links	API key
POST	`/api/ai/links`	Create a short link (optional custom slug)	API key
GET	`/api/ai/links/{slug}`	Retrieve a specific link by slug	API key
PATCH	`/api/ai/links/{slug}`	Partially update a link (only supplied fields change)	API key
POST	`/api/ai/links/{slug}/share`	Share or unshare a link with the organization	API key
GET	`/api/ai/keys`	List active API keys (metadata only — no raw values)	Entra ID
POST	`/api/ai/keys`	Generate a new API key (raw key returned once)	Entra ID
DELETE	`/api/ai/keys/{keyId}`	Revoke an API key immediately	Entra ID

Authentication

All /api/ai/links/* endpoints require an API key passed in the X-Api-Key request header. Keys are tied to a specific user’s identity — every link created or modified through the API is attributed to that user.

The /api/ai/keys/* endpoints (for generating and revoking keys) use Microsoft Entra ID session authentication — the same sign-in used by the dashboard. They cannot be called with an API key.

Generating a key

Sign in to the Link Redirector dashboard, navigate to Settings › API Keys, and click Generate Key. The raw key is shown exactly once — copy and store it securely before closing the dialog.

Keys can also be generated programmatically via POST /api/ai/keys from any authenticated Entra ID session (see Create a key).

Key format

Every key starts with the prefix lrk_ followed by a 43-character base64url string. Example: lrk_abc123XYZ…

Using a key

# Include the key in every request to /api/ai/links/*
GET https://links.inworksllc.com/api/ai/links
X-Api-Key: lrk_your_key_here

A missing or invalid key returns 401 Unauthorized. Revoked keys take effect immediately — any agent using a revoked key will receive 401 on the very next call.

Links

GET /api/ai/links

Returns short links created by the caller, plus any links shared with the organization. Results are ordered by creation date, newest first.

Query parameters

Name	Type	Default	Description
`limit` optional	integer	50	Maximum number of links to return. Min 1, max 200.

Example response

{
  "count": 2,
  "links": [
    {
      "slug":           "q3-deck",
      "shortLink":      "https://links.inworksllc.com/go/q3-deck",
      "destinationUrl": "https://sharepoint.com/sites/finance/Q3.pptx",
      "title":          "Q3 Board Deck",
      "createdBy":      "Alex Johnson",
      "createdOn":      "2026-07-01T14:22:00Z",
      "clickCount":     14,
      "isShared":       true,
      "isLocked":       false,
      "isOneTime":      false,
      "isPinned":       false
    }
  ]
}

POST /api/ai/links

Creates a new short link attributed to the caller’s identity. Returns 201 Created with the full link object.

Request body

Field	Type	Description
`destinationUrl` optional	string	The URL to redirect to (`http` or `https`). Omit for message-only links.
`title` optional	string	Human-readable label shown in the dashboard and add-in.
`slug` optional	string	Custom short code (letters, numbers, hyphens, underscores; 2–60 chars). Auto-generated if omitted.
`messageText` optional	string	Text shown on the landing page before the visitor proceeds.
`isShared` optional	boolean	When `true`, all org members can see this link. Default: `false`.
`isOneTime` optional	boolean	When `true`, the link expires after the first click. Default: `false`.

Example request

POST /api/ai/links
X-Api-Key: lrk_your_key_here
Content-Type: application/json

{
  "destinationUrl": "https://sharepoint.com/sites/hr/2026BenefitsGuide.pdf",
  "title":          "2026 Benefits Guide",
  "slug":           "benefits-2026",
  "isShared":       true
}

Status codes

Code	Meaning
`201`	Link created — full link object in body
`400`	Invalid URL or slug format
`401`	Missing or invalid API key
`403`	License limit reached (creator or link count)
`409`	Slug already in use — choose a different one or omit it

GET /api/ai/links/{slug}

Returns the link with the given slug. Private links (isShared: false) can only be retrieved by their creator. Returns 403 if the link exists but is not accessible to the caller.

PATCH /api/ai/links/{slug}

Partially updates a link. Only the fields present in the request body are changed — omitted fields are left unchanged. The caller must be the creator of the link. Locked links cannot be updated until isLocked: false is sent first.

Request body (all fields optional)

Field	Type	Description
`destinationUrl`	string	New destination URL.
`title`	string	New display title.
`messageText`	string	New landing page message.
`isShared`	boolean	Change sharing status.
`isLocked`	boolean	Lock or unlock the link.
`isPinned`	boolean	Pin or unpin from the top of the list.

Example — update destination URL only

PATCH /api/ai/links/benefits-2026
X-Api-Key: lrk_your_key_here
Content-Type: application/json

{
  "destinationUrl": "https://sharepoint.com/sites/hr/2026BenefitsGuide-v2.pdf"
}

API Keys

Key management endpoints use Microsoft Entra ID session authentication (not API keys). These are the same credentials used to sign in to the dashboard.

GET /api/ai/keys

Returns metadata for all active API keys belonging to the caller. Raw key values are never returned after creation.

{
  "count": 1,
  "keys": [
    {
      "keyId":      "a3f9c2d1",
      "createdOn":  "2026-07-01T09:00:00Z",
      "lastUsedOn": "2026-07-15T14:33:00Z"
    }
  ]
}

POST /api/ai/keys

Generates a new API key for the authenticated user. The raw key is returned exactly once in the key field. It is not stored and cannot be retrieved again — store it securely immediately.

{
  "keyId":     "a3f9c2d1",
  "key":       "lrk_abc123XYZ…",
  "createdOn": "2026-07-16T10:00:00Z",
  "warning":   "Store this key securely — it will not be shown again."
}

DELETE /api/ai/keys/{keyId}

Permanently revokes the key with the given keyId. Any agent using the revoked key will immediately receive 401 responses. Returns 204 No Content on success.

Error Responses

All error responses use a consistent JSON structure with two fields:

{
  "error":   "slug_taken",
  "message": "The slug 'q3-deck' is already in use. Choose a different slug or omit it to auto-generate one."
}

Code	Common `error` values
`400`	`invalid_url`, `invalid_slug`, `invalid_body`, `link_locked`
`401`	`unauthorized`
`403`	`forbidden`, `license_invalid`, `creator_limit_reached`, `trial_link_limit_reached`
`404`	`not_found`
`409`	`slug_taken`

OpenAPI Specification

A complete OpenAPI 3.0 specification is available in the repository root as openapi.yaml. It can be imported into tools like Postman, Insomnia, or any MCP server configuration that consumes an OpenAPI spec to build AI tools automatically.

For questions or issues with the API, contact support@inworksllc.com.