Developers

Everything you do in Nimbli also works from a script or an AI assistant, with the same rules and the same 25-link limit. They act as you and can't do more than you can.

Connect an AI assistant

Claude, ChatGPT or any client that speaks MCP.

In Claude, open Settings, then Connectors, then "Add custom connector". Paste the address below and sign in when asked.

https://nimbli.app/mcp

Then ask: "Shorten https://shop.example.com/spring as spring-sale." Deleting a link always asks you first. Assistants never make tokens, change teams or delete your account.

An assistant gets these tools: myTeams (the teams you're in), teamLinks (list and search a team's links), linkByCode, linkClicks, createLink, createLinks (up to 50 at once), changeDestination, setNote, renameLink, deleteLink, askForReview and reportLink.

API tokens

A token lets a script act as you, in the team you pick.

API basics

Base address: https://nimbli.app/api/v1 · openapi.json
Sign in: Authorization: Bearer <token>. Every call is a POST to its operation's address, with its params as JSON.
Safe retries: Send Idempotency-Key when creating; a retry with the same key returns the same link.
Limits: Shared with the dashboard: 20 new links an hour and 100 a day per team; 600 calls a minute. Every answer has RateLimit and RateLimit-Policy; when limited, Retry-After.
Paging: Lists return up to 100 items a call, with a next cursor to send back as after.

listTeams POST

The teams you're in, by name. Pass a team's id as team to make or list its links.

curl -X POST https://nimbli.app/api/v1/listTeams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"limit":50}'

Example answer

{
  "data": [
    {
      "id": "team_01JB8XQ2F4ZK7M3N9P5R2T6V8W",
      "name": "name"
    }
  ],
  "next": "eyJrIjpbIjIwMzAtMDEtMTUiXX0"
}

createLink POST

Makes a short link in a team, with a random 7-character code, and optionally a short link name (3 to 50 of a-z 0-9 - _) and a note. The destination must be an https address that isn't an IP address, a Nimbli link, another link shortener or blocked. A team makes at most 25 links, 20 an hour and 100 a day (10 a day in its first week). Send an Idempotency-Key header to retry safely.

curl -X POST https://nimbli.app/api/v1/createLink \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"team":"team_01JB8XQ2F4ZK7M3N9P5R2T6V8W","destination":"destination","name":"name","note":"note"}'

Params

team: an id, team_... · required
destination: text · required
name: text or null · optional
note: text or null · optional, 0 to 100 characters

Example answer

{
  "id": "link_01JB8XQ2F4ZK7M3N9P5R2T6V8W",
  "code": "code",
  "name": "name",
  "destination": "https://example.com/page",
  "note": "note",
  "state": "active",
  "createdAt": "2030-01-15T09:30:00.000Z",
  "changedAt": "2030-01-15T09:30:00.000Z"
}

Errors to branch on

400blocked_destinationNimbli doesn't allow links to that site.

503check_unavailableWe couldn't check this address. Try again in a minute.

400invalid_destinationThat address is too long: 2,048 characters at most.

400invalid_nameUse 3 to 50 lowercase letters, numbers, - and _.

400invalid_noteA note can have letters, numbers, spaces and - _ , . ' ( ) & ! ? : only.

429limit_reachedThis team invited that address in the last day. Try again tomorrow.

409name_takenThat name is taken. Try another.

400private_destinationThat address is on a private network.

400reserved_nameThat name is reserved. Try another.

400shortener_destinationNimbli links can't point to other Nimbli links.

409team_full

400unsafe_destinationThis address is on Google's list of unsafe sites.

createLinks POST

Makes up to 50 links in a team at once. Each gets its own result: the link, or the status and message createLink would have failed with. One failing doesn't stop the others.

curl -X POST https://nimbli.app/api/v1/createLinks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"team":"team_01JB8XQ2F4ZK7M3N9P5R2T6V8W","links":[{"destination":"destination","name":"name","note":"note"}]}'

Params

team: an id, team_... · required
links: a list of an object · required

Example answer

{
  "results": [
    {
      "link": {
        "id": "link_01JB8XQ2F4ZK7M3N9P5R2T6V8W",
        "code": "code",
        "name": "name",
        "destination": "https://example.com/page",
        "note": "note",
        "state": "active",
        "createdAt": "2030-01-15T09:30:00.000Z",
        "changedAt": "2030-01-15T09:30:00.000Z"
      },
      "status": 3,
      "code": "code",
      "message": "message"
    }
  ]
}

listLinks POST

A team's links, newest first, deleted ones left out. state keeps only active, flagged or disabled links; q matches the code, short link name, destination or note.

curl -X POST https://nimbli.app/api/v1/listLinks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"team":"team_01JB8XQ2F4ZK7M3N9P5R2T6V8W","state":"active","q":"q","limit":50}'

Params

team: an id, team_... · required
state: one of "active", "flagged", "disabled" or null · optional
q: text or null · optional

Example answer

{
  "data": [
    {
      "id": "link_01JB8XQ2F4ZK7M3N9P5R2T6V8W",
      "code": "code",
      "name": "name",
      "destination": "https://example.com/page",
      "note": "note",
      "state": "active",
      "createdAt": "2030-01-15T09:30:00.000Z",
      "changedAt": "2030-01-15T09:30:00.000Z"
    }
  ],
  "next": "eyJrIjpbIjIwMzAtMDEtMTUiXX0"
}

getLink POST

One link by its code. A deleted link, or one outside your teams, is 404.

curl -X POST https://nimbli.app/api/v1/getLink \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"code":"codexxx"}'

Params

code: text · required, 7 to 7 characters

Example answer

{
  "id": "link_01JB8XQ2F4ZK7M3N9P5R2T6V8W",
  "code": "code",
  "name": "name",
  "destination": "https://example.com/page",
  "note": "note",
  "state": "active",
  "createdAt": "2030-01-15T09:30:00.000Z",
  "changedAt": "2030-01-15T09:30:00.000Z"
}

setDestination POST

Changes where a link goes. Printed QR codes and shared links follow. A flagged or disabled link can't change.

curl -X POST https://nimbli.app/api/v1/setDestination \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"code":"codexxx","destination":"destination"}'

Params

code: text · required, 7 to 7 characters
destination: text · required

Example answer

{
  "id": "link_01JB8XQ2F4ZK7M3N9P5R2T6V8W",
  "code": "code",
  "name": "name",
  "destination": "https://example.com/page",
  "note": "note",
  "state": "active",
  "createdAt": "2030-01-15T09:30:00.000Z",
  "changedAt": "2030-01-15T09:30:00.000Z"
}

Errors to branch on

400blocked_destinationNimbli doesn't allow links to that site.

503check_unavailableWe couldn't check this address. Try again in a minute.

400invalid_destinationThat address is too long: 2,048 characters at most.

429limit_reachedThis team invited that address in the last day. Try again tomorrow.

409link_disabledNimbli disabled this link, so it can't be changed.

409link_flaggedYou can't change where it goes while it's flagged. Ask for a review.

400private_destinationThat address is on a private network.

400shortener_destinationNimbli links can't point to other Nimbli links.

400unsafe_destinationThis address is on Google's list of unsafe sites.

setNote POST

Sets a link's note to self, or clears it with null.

curl -X POST https://nimbli.app/api/v1/setNote \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"code":"codexxx","note":"note"}'

Params

code: text · required, 7 to 7 characters
note: text or null · required, 0 to 100 characters

Example answer

{
  "id": "link_01JB8XQ2F4ZK7M3N9P5R2T6V8W",
  "code": "code",
  "name": "name",
  "destination": "https://example.com/page",
  "note": "note",
  "state": "active",
  "createdAt": "2030-01-15T09:30:00.000Z",
  "changedAt": "2030-01-15T09:30:00.000Z"
}

Errors to branch on

400invalid_noteA note can have letters, numbers, spaces and - _ , . ' ( ) & ! ? : only.

renameLink POST

Sets, changes or removes (null) a link's short link name. The old name stops working at once and stays your team's; QR codes keep working, since they use the code.

curl -X POST https://nimbli.app/api/v1/renameLink \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"code":"codexxx","name":"name"}'

Params

code: text · required, 7 to 7 characters
name: text or null · required

Example answer

{
  "id": "link_01JB8XQ2F4ZK7M3N9P5R2T6V8W",
  "code": "code",
  "name": "name",
  "destination": "https://example.com/page",
  "note": "note",
  "state": "active",
  "createdAt": "2030-01-15T09:30:00.000Z",
  "changedAt": "2030-01-15T09:30:00.000Z"
}

Errors to branch on

400invalid_nameUse 3 to 50 lowercase letters, numbers, - and _.

429limit_reachedThis team invited that address in the last day. Try again tomorrow.

409link_disabledNimbli disabled this link, so it can't be changed.

409link_flaggedYou can't change where it goes while it's flagged. Ask for a review.

409name_takenThat name is taken. Try another.

400reserved_nameThat name is reserved. Try another.

deleteLink POST

Deletes a link: it answers "link not found" at once, and its code and name are never used again.

curl -X POST https://nimbli.app/api/v1/deleteLink \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"code":"codexxx"}'

Params

code: text · required, 7 to 7 characters

Example answer

null

Errors to branch on

429limit_reachedThis team invited that address in the last day. Try again tomorrow.

linkClicks POST

A link's clicks per day for the last 30 days, oldest first, with the totals for 7 and 30 days.

curl -X POST https://nimbli.app/api/v1/linkClicks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"code":"codexxx"}'

Params

code: text · required, 7 to 7 characters

Example answer

{
  "days": [
    {
      "date": "2030-01-15",
      "clicks": 3
    }
  ],
  "last7": 3,
  "last30": 3
}

Errors

Each is application/problem+json with the status, a code, a detail to show, and the field at fault.