# Create a short link

Shortens a public http(s) address into a /go/<code> link that counts clicks.

|  |  |
| --- | --- |
| REST | `POST /api/v1/agents/{agent_id}/short-links` |
| MCP tool | `create_short_link` |
| Classification | **Write** |
| Scope | `agents:write` |
| Minimum role on the agent | editor |
| Confirmation | Not needed |
| Retry safety | Send an `Idempotency-Key` header (REST) or `idempotency_key` argument (MCP) to retry safely |
| Success status | 201 |

## What it does

Shortens a public http(s) address into a /go/<code> link that counts clicks. It works while the agent is published. Plans limit how many an agent keeps (plan_limit when full).

## Side effects

Creates a public /go/ link that redirects whoever opens it. Counts toward the plan limit for short links.

## Inputs

| Name | Type | Required | In | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | string | yes | path | The agent id (agt_...), from list_agents. |
| `url` | string | yes | body | The public http(s) address to send people to. |
| `title` | string | no | body | A name to recognize the link by. |

## Example

REST:

```bash
curl -X POST "https://covo.lanaai.io/api/v1/agents/agt_4edc89bb2964/short-links" \
  -H "Authorization: Bearer $COVO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://example.com/spring-menu","title":"Spring menu"}'
```

MCP (POST /mcp):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_short_link",
    "arguments": {
      "agent_id": "agt_4edc89bb2964",
      "url": "https://example.com/spring-menu",
      "title": "Spring menu"
    }
  }
}
```

## Response

Returns an object with `id`, `short_url`, `url`, `title`, `enabled`, `clicks`, `total_clicks`, `last_clicked` and `created_at`. This is a real response, shortened to two items per list.

201 response:

```json
{
  "id": "33f5aef6-f05a-4a0e-8716-76aed5e209f9",
  "short_url": "https://covo.lanaai.io/go/NAqH5mp",
  "url": "https://example.com/spring-menu",
  "title": "Spring menu",
  "enabled": true,
  "clicks": 0,
  "total_clicks": 0,
  "last_clicked": null,
  "created_at": "2026-10-07T20:14:42.017Z"
}
```

Over MCP the same object comes back as the tool result, in `structuredContent` and as JSON text.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthorized` | No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect. |
| 403 | `account_suspended` | The account that owns the token is paused. |
| 403 | `insufficient_scope` | The token lacks `agents:write`. |
| 404 | `agent_not_found` | Unknown agent, or not reachable with this token. |
| 400 | `bad_request` | An input is invalid; `field` names it. |
| 409, 422 | `idempotency_in_progress`, `idempotency_key_reused` | See Idempotency on the REST page. |
| 403 | `plan_limit` | The plan is full; `details` has the limit. |
| 429 | `rate_limited` | Wait `Retry-After` seconds. |