Destinations
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
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/workspaces/{workspace_public_id}/destinations | destinations:read |
POST | /api/v1/workspaces/{workspace_public_id}/destinations | destinations: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
type | config | Plan |
|---|---|---|
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
httpson 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"
}
]| Field | Notes |
|---|---|
value | The email recipients (comma-separated) or the webhook URL. |
team_public_ids, team_names | The teams the destination is limited to. Empty when it’s workspace-wide. |
team_public_id, team_name | The destination’s original team, kept for older integrations. |
Create a destination
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | |
type | string | Yes | email, webhook, slack, discord or msteams. |
config | object | Yes | See destination types. |
team_public_ids | array of strings | No | Teams 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.
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | |
type | string | Yes | |
config | object | No | Replaces the configuration. Leave it out to keep the current one. |
team_public_ids | array of strings | No | The 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
| Status | Response | When |
|---|---|---|
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 similar | A team in team_public_ids is unknown or in another workspace. |
403 | code: workspace_permission_denied | You’re a read-only member. |
403 | code: plan_limit_exceeded | The owner’s plan doesn’t include this destination type. |
404 | {"error": "destination not found"}, or code: destination_not_found | The destination doesn’t exist in this workspace, or you can’t see it. |
The workspace in the path is checked first:
400invalid_workspace_id;403api_key_workspace_mismatch, for a key restricted to another workspace;404workspace_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.