---
title: "Create a short link"
method: POST
path: "/links"
tags: ["Links"]
---

# Create a short link

`POST /links`

## Request

- Base URL: `https://api.rizamo.com/v1`
- URL: `https://api.rizamo.com/v1/links`
- Auth: HTTP bearer

A short address on Rizamo's link host that sends people on to `url` and counts each click, by day and country. Nothing about the person who clicks is kept: no IP address, cookie or device. Link previews (Instagram, Facebook, WhatsApp, Slack, X and others) and bots are not counted. Without `profileId`, the link is yours (the person, key or agent that made it) and people limited to some profiles do not see it. A team makes up to 1,000 links in 24 hours, and only once it has a connected account or a paid plan (403 until then).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, required: Where the link sends people: a public http or https address, up to 2,048 characters, without line breaks. It is kept as the URL standard writes it (`url` in the answer: the host in ASCII, the path encoded). Rizamo's own short links are refused, so a link never points at another.
  - `utm` object: UTM tags Rizamo adds to `url` as `utm_*` parameters, so your own analytics (Google Analytics and the like) see where visitors came from. A tag the address already has stays as it is, never overwritten; empty ones add nothing. The tagged address is what `url` shows in the answer, and it must fit in 2,048 characters too.
    - `source` string: `utm_source`: where visitors come from, such as instagram.
    - `medium` string: `utm_medium`: the kind of traffic, such as social.
    - `campaign` string: `utm_campaign`: the campaign, such as autumn-menu.
    - `term` string: `utm_term`: a keyword, mostly for paid search.
    - `content` string: `utm_content`: tells apart links of one campaign.
  - `profileId` string: A profile you reach, which the link belongs to.
  - `expiresAt` string, date-time: When it stops working, in the future. Left out, it never expires.

## Response `201`

OK

- Link
  - `id` string, required
  - `code` string, required
  - `shortUrl` string, required: The link to share. It sends people on to `url` and counts the click.
  - `url` string, required: Where it sends people.
  - `profileId` string, nullable, required: The profile it belongs to. Null: it is its creator's (the person, key or agent that made it).
  - `source` object, nullable, required: What made the link, when Rizamo made it for something: a comment automation's messages or a post. Null for links made through the API.
    - `type` 'comment_automation' | 'post', required
    - `id` string, required
  - `createdBy` union, required
    - object
      - `type` 'agent', required
      - `agent` 'claude' | 'chatgpt' | 'claudecode' | 'cursor' | 'codex' | 'gemini' | 'perplexity' | 'openclaw' | 'n8n' | 'make' | 'zapier', nullable, required
      - `name` string, required
      - `agentId` string
      - `onBehalfOf` object: The person whose agent it is, who connected it and whom it acts as, with their role: "Ana via Claude Code". Events from before 2026-11-02 have it too, with the person's name now. Left out of an agent with no person, and of other records from before. After the person's erasure, `name` is "A former member" and `userId` empty.
        - `userId` string, required
        - `name` string, required
    - object
      - `type` 'user', required
      - `userId` string, required
      - `name` string, required
      - `initials` string, required
    - object
      - `type` 'api_key', required
      - `keyId` string, required
      - `name` string, required
    - object
      - `type` 'automation', required
      - `automationId` string, required
      - `name` string, required
  - `clicks` integer, required: Clicks so far. Link previews and bots are not counted; one person clicking twice counts twice.
  - `expiresAt` string, date-time, nullable, required: From then on the link answers 404. Null: it never expires.
  - `disabledAt` string, date-time, nullable, required: When Rizamo disabled it for breaking the Acceptable Use Policy: it answers 404 from then on, whatever changes. Null for every other link.
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400`: `invalid_request`: A field is missing or wrong, or the request cannot be done as asked: the message names the field or says what to change.
- `401`: `unauthorized`: No API key or sign-in, or the key does not work: it was deleted, or it expired.
- `403`: `forbidden`: The caller may not do this: the key or agent lacks the scope (the message names it), or the action needs another role or a fresh sign-in.
- `404`: `not_found`: No such object, or it is outside your team or the profiles your key reaches.
- `409`: `conflict`: The object's state does not allow it now, such as an account that needs a new login. `queue_empty`: A post with `queue: true` whose profile has no posting times: set them, or give a `scheduledAt`. `queue_full`: No posting time free for the post's accounts in the next 90 days: add times, or give a `scheduledAt`. `idempotency_key_in_use`: A request with this `Idempotency-Key` is still running: try again in a moment.
- `413`: `payload_too_large`: The body is over 1 MB: files go up through the upload links of `POST /v1/media`.
- `415`: `unsupported_media_type`: The body is not JSON: send it with `Content-Type: application/json`.
- `422`: `capability_missing`: The account cannot do this: see its `capabilities`. `idempotency_key_reused`: This `Idempotency-Key` was used for a different request in the last 24 hours: send a new key.
- `429`: `rate_limited`: Over one of Rizamo's limits, or a network asked Rizamo to slow down: wait for `Retry-After` seconds, or as long as the message says.
- `500`: `internal`: Our side failed: retry, and send the `requestId` if it keeps failing.
- `503`: `timeout`: The request took too long to work out, most often a report: try again in a moment, or ask a report for a shorter period or one profile.

---

[API](https://skmtc.dev/rizamo/apis/rizamo-api.md) - [All operations](https://skmtc.dev/rizamo/apis/rizamo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rizamo/apis/rizamo-api/revisions/31b0c1b1ffb5?raw)
