Skip to main content

Agent-first

Build with agents

Most LinkScale integrations are now written by a coding agent. Give it the contract, the rules and a key, and it can build the rest. Everything on this site is also published in a form an agent can read directly.

1. Start with the agent prompt

Paste it before your task. It points the agent at the OpenAPI contract, sets authentication, and lists the rules that keep it from inventing fields or writing without your confirmation.

Agent prompt
You are helping me build with LinkScale (links, landing pages, Shield, analytics, social accounts and creator-platform integrations) through its REST API and MCP server.

Sources of truth (fetch them before writing code):
- OpenAPI 3.0 contract: https://docs.linkscale.to/openapi.bundle.json
- Agent index: https://docs.linkscale.to/llms.txt
- Full guides in one file: https://docs.linkscale.to/llms-full.txt

Access:
- REST base URL: https://dashboard.linkscale.to (paths start with /api/v1 or /api/v2)
- MCP server: https://dashboard.linkscale.to/api/mcp (JSON-RPC 2.0 over HTTP POST, same Bearer key; GET returns 405). Call initialize, then tools/list, and pick tools from their descriptions.
- OAuth discovery for MCP clients: https://dashboard.linkscale.to/.well-known/oauth-protected-resource
- API keys and their permissions: https://dashboard.linkscale.to/mcp

Rules you must follow:
1. The OpenAPI document is the contract. Never invent an endpoint, field, parameter or permission. If something is not in it, say so instead of guessing.
2. Authenticate with `Authorization: Bearer $LINKSCALE_API_KEY`. Read the key from the environment; never hardcode, log, print or commit it, and never ship it to browser code.
3. Check the HTTP status before trusting a body. Over MCP, also check `result.isError` and the JSON-RPC `error` even when HTTP is 200.
4. A 403 means the key lacks a permission (for example `links.read`). Name the missing permission; do not retry around it.
5. Retry only reads, only on 429 and 5xx, with exponential backoff and the server's retry delay when given. Never blindly retry a write: read the current state first.
6. Ignore response fields you do not recognise. Some list fields (`geo_rules`, Shield `rules`, `folders`) REPLACE the whole array: read, modify, then write the full list back.
7. Before any create, update or delete, show me the exact request and wait for my confirmation. MCP mutation tools also require `confirm: true`.
8. A null or pending value is not zero, and amounts in different currencies are never added together.
9. Never ask me for passwords, cookies or two-factor codes. Platform sign-ins happen in the LinkScale dashboard.

Start by fetching the agent index, then tell me which endpoints or MCP tools you plan to use and which key permissions they need.

My task: <describe what you want to build>

2. Or scaffold an automation

For a scheduled script or a sync job: the agent plans first, waits for your review, then writes a typed client, an idempotent script that runs in dry-run by default, and a smoke test.

Automation setup prompt
Set up a small, production-ready LinkScale automation in this repository.

Sources of truth (fetch them before writing code):
- OpenAPI 3.0 contract: https://docs.linkscale.to/openapi.bundle.json
- Agent index: https://docs.linkscale.to/llms.txt
- Full guides in one file: https://docs.linkscale.to/llms-full.txt

Access:
- REST base URL: https://dashboard.linkscale.to (paths start with /api/v1 or /api/v2)
- MCP server: https://dashboard.linkscale.to/api/mcp (JSON-RPC 2.0 over HTTP POST, same Bearer key; GET returns 405). Call initialize, then tools/list, and pick tools from their descriptions.
- OAuth discovery for MCP clients: https://dashboard.linkscale.to/.well-known/oauth-protected-resource
- API keys and their permissions: https://dashboard.linkscale.to/mcp

Build it in this order and stop for my review after step 2:
1. Read the agent index and the OpenAPI contract. List the exact operations the automation needs and the API key permissions each one requires.
2. Propose the file layout and wait for my go-ahead.
3. Add `.env.example` with `LINKSCALE_API_KEY=` and make sure the real `.env` is git-ignored.
4. Write a typed TypeScript client: one `request()` wrapper (base URL, Bearer header, JSON, timeout), typed responses taken from the contract, pagination helpers that follow the documented cursor or page fields, and backoff that retries reads only.
5. Implement the automation itself, idempotent so a re-run never duplicates work, with dry-run as the default and writes behind an explicit `--apply` flag.
6. Add one read-only smoke test (list links) and a README section: setup, required permissions, how to run, how to schedule it.

Rules you must follow:
1. The OpenAPI document is the contract. Never invent an endpoint, field, parameter or permission. If something is not in it, say so instead of guessing.
2. Authenticate with `Authorization: Bearer $LINKSCALE_API_KEY`. Read the key from the environment; never hardcode, log, print or commit it, and never ship it to browser code.
3. Check the HTTP status before trusting a body. Over MCP, also check `result.isError` and the JSON-RPC `error` even when HTTP is 200.
4. A 403 means the key lacks a permission (for example `links.read`). Name the missing permission; do not retry around it.
5. Retry only reads, only on 429 and 5xx, with exponential backoff and the server's retry delay when given. Never blindly retry a write: read the current state first.
6. Ignore response fields you do not recognise. Some list fields (`geo_rules`, Shield `rules`, `folders`) REPLACE the whole array: read, modify, then write the full list back.
7. Before any create, update or delete, show me the exact request and wait for my confirmation. MCP mutation tools also require `confirm: true`.
8. A null or pending value is not zero, and amounts in different currencies are never added together.
9. Never ask me for passwords, cookies or two-factor codes. Platform sign-ins happen in the LinkScale dashboard.

The automation: <for example "every morning, post yesterday's top 10 links by clicks to Slack">

3. Connect over MCP

The MCP server at https://dashboard.linkscale.to/api/mcp exposes the same project data as tools. Create a key with the permissions you need in the dashboard, set LINKSCALE_API_KEY, and add this to your MCP client configuration. Clients that support OAuth can discover it from the protected-resource metadata instead.

mcp.json
{
  "mcpServers": {
    "linkscale": {
      "type": "http",
      "url": "https://dashboard.linkscale.to/api/mcp",
      "headers": {
        "Authorization": "Bearer ${LINKSCALE_API_KEY}"
      }
    }
  }
}

Read the MCP guide for tool selection, paging and the read-only review prompt.

4. Machine-readable docs

Generated from the same source as these pages on every release, so they never drift from the reference.

https://docs.linkscale.to/llms.txtIndex of every guide and endpoint, with the agent prompt.https://docs.linkscale.to/llms-full.txtAll guides in one Markdown file.https://docs.linkscale.to/openapi.bundle.jsonThe complete OpenAPI 3.0 contract.

Every guide is also available as Markdown: add .md to its address, for example /guides/overview.md.