Skip to content
Destinations

Destinations

Availability: Email destinations are available on every plan, including Free. Slack, Discord and Microsoft Teams need Starter or higher; webhooks need Professional or higher. The workspace owner’s plan applies. API keys need destinations:read to list destinations, and destinations:write to create, change and delete them.

A destination is where a workspace’s reports and alerts are sent: an email list, a webhook, or a Slack, Discord or Microsoft Teams channel. See webhooks and destinations. Identify a destination by its public_id. To send a report or alert to it, list its public ID in destination_public_ids on the report rule.

These endpoints return their objects directly, without a data wrapper, and most of their errors carry only an error message.

Endpoints

MethodPathScope
GET/api/v1/workspaces/{workspace_public_id}/destinationsdestinations:read
POST/api/v1/workspaces/{workspace_public_id}/destinationsdestinations:write
PUT/api/v1/workspaces/{workspace_public_id}/destinations/{destination_public_id}destinations:write
DELETE/api/v1/workspaces/{workspace_public_id}/destinations/{destination_public_id}destinations:write

Every workspace member can list destinations. Owners, administrators and collaborators can create, change and delete them.

Destination types

typeconfigPlan
email{"to": ["ops@example.com", "team@example.com"]}. A comma-separated string also works. Duplicates are dropped.Every plan
slack, discord, msteams{"webhook_url": "https://..."}, the channel’s incoming webhook URL.Starter and higher
webhook{"webhook_url": "https://..."}, your endpoint.Professional and higher

Webhook URLs must:

  • use https on the default port (443);
  • point at a public host. Shortn refuses private and internal addresses.

The whole config can be up to 16 KB.

List destinations

Returns the workspace’s destinations you can see. Workspace owners and administrators see every destination; other members see workspace-wide destinations and those of teams they belong to.

curl https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/destinations \
  -H "Authorization: Bearer $SHORTN_API_KEY"
[
  {
    "id": 9,
    "public_id": "f2a7c9e1-5d3b-4b80-9e6a-1c4d7f0b2e35",
    "name": "Marketing inbox",
    "type": "email",
    "value": "marketing@example.com",
    "team_public_id": "",
    "team_name": "",
    "team_public_ids": [],
    "team_names": [],
    "workspace_wide": true,
    "created_at": "2026-09-14T08:20:00Z"
  }
]
FieldNotes
valueThe email recipients (comma-separated) or the webhook URL.
team_public_ids, team_namesThe teams the destination is limited to. Empty when it’s workspace-wide.
team_public_id, team_nameThe destination’s original team, kept for older integrations.

Create a destination

FieldTypeRequiredNotes
namestringYes
typestringYesemail, webhook, slack, discord or msteams.
configobjectYesSee destination types.
team_public_idsarray of stringsNoTeams to limit the destination to. Leave it out for a workspace-wide destination.
curl -X POST https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/destinations \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Growth channel", "type": "slack", "config": {"webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX"}}'

The response is 201:

{
  "id": 10,
  "public_id": "a6e3b1d9-7c42-4f15-8b0e-3d9c5a7f1e64",
  "name": "Growth channel",
  "type": "slack",
  "workspace_wide": true,
  "team_public_ids": [],
  "team_names": [],
  "created_at": "2026-11-16T10:05:00Z"
}

A type the owner’s plan doesn’t include returns 403, with feature set to webhooks_integrations and required_plan set to starter or professional:

{
  "code": "plan_limit_exceeded",
  "error": "Webhook destinations require the Professional plan or higher",
  "hint": "Upgrade to a plan that includes this feature or raises this limit.",
  "feature": "webhooks_integrations",
  "limit": 0,
  "current": 0,
  "required_plan": "professional",
  "upgrade_url": "/profile/billing"
}

Update a destination

PUT needs name and type every time.

FieldTypeRequiredNotes
namestringYes
typestringYes
configobjectNoReplaces the configuration. Leave it out to keep the current one.
team_public_idsarray of stringsNoThe destination’s complete list of teams. Send [] to make it workspace-wide. Leave it out to keep the current teams.
curl -X PUT https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/destinations/f2a7c9e1-5d3b-4b80-9e6a-1c4d7f0b2e35 \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing inbox", "type": "email", "config": {"to": ["marketing@example.com", "cmo@example.com"]}}'
{
  "success": true
}

When you send team_public_ids, the response also has the destination’s teams:

{
  "success": true,
  "workspace_wide": false,
  "team_public_ids": ["5b7e0c2d-91a4-4f3e-8d6b-0a2c4e6f8b13"],
  "team_names": ["Paid Social"],
  "teams": [
    {
      "team_id": 31,
      "team_public_id": "5b7e0c2d-91a4-4f3e-8d6b-0a2c4e6f8b13",
      "team_name": "Paid Social"
    }
  ]
}

Delete a destination

curl -X DELETE https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/destinations/f2a7c9e1-5d3b-4b80-9e6a-1c4d7f0b2e35 \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{
  "success": true
}

Errors

StatusResponseWhen
400{"error": "invalid request"}The body isn’t valid JSON.
400{"error": "name is required"}, {"error": "invalid type: ..."}name or type is missing or wrong.
400{"error": "webhook URL is required"}, {"error": "invalid webhook URL: ..."}The webhook URL is missing, isn’t https, uses another port, or points at a private address.
400{"error": "email destination requires at least one recipient"}, {"error": "invalid email destination"}No recipients, or an address that isn’t valid.
400{"error": "destination config is too large"}config is over 16 KB.
400{"error": "team not found"} and similarA team in team_public_ids is unknown or in another workspace.
403code: workspace_permission_deniedYou’re a read-only member.
403code: plan_limit_exceededThe owner’s plan doesn’t include this destination type.
404{"error": "destination not found"}, or code: destination_not_foundThe destination doesn’t exist in this workspace, or you can’t see it.

The workspace in the path is checked first:

  • 400 invalid_workspace_id;
  • 403 api_key_workspace_mismatch, for a key restricted to another workspace;
  • 404 workspace_not_found, which an archived workspace also returns.

Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.

Last updated on