UTM templates

UTM templates endpoints of the URLCrop API: 5 operations.

List UTM templates

GET/utm-templates

Scope links:read
starter plan and above

Parameters

Name	In	Type	Description
X-Workspace-Id	header	string	Workspace to act on. Required for session requests on workspace-scoped routes; optional for API keys (must equal the key's workspace, otherwise `403 workspace_mismatch`). For a session, a workspace the user is not an active member of (another tenant, a removed membership, a malformed or unknown id) answers `404 resource_not_found`, never `403`.
cursor	query	string	Opaque cursor from `pagination.next_cursor`.
limit	query	integer	Page size (1–100).

Request example

GET /utm-templatescURL

curl 'https://api.urlcrop.com/v1/utm-templates' \
  -H 'Authorization: Bearer uc_live_…'

Responses

200 response

Templates

UtmTemplateList schema and example

Field	Type	Description
datarequired	array of UtmTemplate
data[].idrequired	string
data[].objectrequired	string	Value: `utm_template`
data[].workspace_idrequired	string
data[].is_test	boolean
data[].namerequired	string	max length 80
data[].utmrequired	Utm	UTM parameters appended to the destination. Values may contain `{{slug}}`, `{{domain}}`, `{{campaign}}`.
data[].utm.source	string	max length 200
data[].utm.medium	string	max length 200
data[].utm.campaign	string	max length 200
data[].utm.term	string	max length 200
data[].utm.content	string	max length 200
data[].created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
data[].updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
paginationrequired	Pagination
pagination.limitrequired	integer
pagination.has_morerequired	boolean
pagination.next_cursorrequired	string \| null	Pass as `cursor` to fetch the next page. `null` on the last page.
pagination.total	integer	Only with `include_total=true`; estimated above 10,000.

200 response: 200 responseJSON

{
  "data": [
    {
      "id": "utm_01JB4PE5F6G7H8J9K0L1M2N3P4",
      "object": "utm_template",
      "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
      "is_test": false,
      "name": "string",
      "utm": {
        "source": "string",
        "medium": "string",
        "campaign": "string",
        "term": "string",
        "content": "string"
      },
      "created_at": "2026-12-05T10:15:30.000Z",
      "updated_at": "2026-12-05T10:15:30.000Z"
    }
  ],
  "pagination": {
    "limit": 0,
    "has_more": false,
    "next_cursor": "string",
    "total": 0
  }
}

Example generated from the schema.

400 response

Malformed request (invalid_json, invalid_query, missing_header, invalid_cursor, invalid_sort, invalid_expand). Any credentialed operation can return it: a credential in the query string (api_key, access_token) is invalid_query, and a session request without X-Workspace-Id on a workspace-scoped route is missing_header.

Error codes: invalid_json, invalid_query, missing_header, invalid_cursor, invalid_sort, invalid_expand

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

400 response: missing headerJSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_header",
    "message": "The X-Workspace-Id header is required for session requests.",
    "param": "X-Workspace-Id",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#missing_header"
  }
}

401 response

Missing or invalid credentials. Always code: unauthenticated; details[0].code gives the reason (missing_credentials, invalid_api_key, api_key_revoked, api_key_expired, session_expired, publishable_key_not_allowed).

Error codes: unauthenticated

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

401 response: unauthenticatedJSON

{
  "error": {
    "type": "authentication_error",
    "code": "unauthenticated",
    "message": "The API key is not valid.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#unauthenticated",
    "details": [
      {
        "path": "Authorization",
        "code": "invalid_api_key",
        "message": "No key matches this secret"
      }
    ]
  }
}

403 response

Permitted credential but not allowed: insufficient_scope, insufficient_role, workspace_mismatch, wrong_environment, two_factor_required (also Owner/Admin writes on Business+ after the 14-day 2FA grace, details[0].grace_ends_at), step_up_required, email_verification_required, signups_paused (sign-up while the platform setting is on), write_blocked_past_due, workspace_suspended, content_policy_hold, origin_not_allowed, or a plan limit (type: plan_limit_error — feature_not_in_plan, plan_limit_reached with param naming the plan limit key). Any credentialed operation can return it: an API key on a session-only route is insufficient_scope, a session write without an allowed Origin is origin_not_allowed, and an API key whose plan has no API access is feature_not_in_plan.

Error codes: two_factor_required, step_up_required, email_verification_required, signups_paused, insufficient_scope, insufficient_role, workspace_mismatch, wrong_environment, workspace_suspended, write_blocked_past_due, content_policy_hold, origin_not_allowed, feature_not_in_plan, plan_limit_reached

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

403 response: plan limit reachedJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "plan_limit_reached",
    "message": "You have created 2,000 of 2,000 links this billing period. Upgrade or buy a pack to continue.",
    "param": "links_per_month",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "plan_limit_reached",
        "message": "Monthly link quota reached",
        "limit": 2000,
        "used": 2000,
        "resets_at": "2026-12-01T00:00:00.000Z",
        "upgrade_to": "business"
      }
    ]
  }
}

403 response: feature not in planJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "feature_not_in_plan",
    "message": "The public API is available on the Pro plan and above.",
    "param": "api_requests_per_day",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "feature_not_in_plan",
        "message": "Upgrade to Pro",
        "upgrade_to": "pro"
      }
    ]
  }
}

403 response: email verification requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "email_verification_required",
    "message": "Verify your email address to create links.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#email_verification_required"
  }
}

403 response: step up requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "step_up_required",
    "message": "Confirm your password or 2FA code to continue.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#step_up_required"
  }
}

404 response

Unknown id, or the resource belongs to another workspace (never distinguished). Also returned when a session's X-Workspace-Id names a workspace the user is not an active member of.

Error codes: resource_not_found

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

404 response: not foundJSON

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "No link with id lnk_01JB4N8ZK3Q9WXYZ0123456789.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#resource_not_found"
  }
}

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

429 response: rate limitedJSON

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Daily API quota of 50,000 requests exhausted. Resets at 00:00 UTC.",
    "param": "daily_quota",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/rate-limits"
  }
}

Create a UTM template (Starter+)

POST/utm-templates

Scope links:write
starter plan and above

Parameters

Name	In	Type	Description
X-Workspace-Id	header	string	Workspace to act on. Required for session requests on workspace-scoped routes; optional for API keys (must equal the key's workspace, otherwise `403 workspace_mismatch`). For a session, a workspace the user is not an active member of (another tenant, a removed membership, a malformed or unknown id) answers `404 resource_not_found`, never `403`.
Idempotency-Key	header	string	Unique string (UUID v4 recommended, ≤ 255 chars). Repeating a POST with the same key and body within 24 hours replays the original response with `Idempotent-Replayed: true`. One-time secrets are never cached: a replay returns them as `null` with `Idempotent-Redacted: secret`.

Request body application/json

Field	Type	Description
namerequired	string
utmrequired	Utm	UTM parameters appended to the destination. Values may contain `{{slug}}`, `{{domain}}`, `{{campaign}}`.
utm.source	string	max length 200
utm.medium	string	max length 200
utm.campaign	string	max length 200
utm.term	string	max length 200
utm.content	string	max length 200

Request body: whatsappJSON

{
  "name": "WhatsApp broadcast",
  "utm": {
    "source": "whatsapp",
    "medium": "broadcast",
    "campaign": "{{campaign}}",
    "content": "{{slug}}"
  }
}

Request example

POST /utm-templatescURL

curl -X POST 'https://api.urlcrop.com/v1/utm-templates' \
  -H 'Authorization: Bearer uc_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "WhatsApp broadcast",
  "utm": {
    "source": "whatsapp",
    "medium": "broadcast",
    "campaign": "{{campaign}}",
    "content": "{{slug}}"
  }
}'

Responses

201 response

Created

UtmTemplate schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `utm_template`
workspace_idrequired	string
is_test	boolean
namerequired	string	max length 80
utmrequired	Utm	UTM parameters appended to the destination. Values may contain `{{slug}}`, `{{domain}}`, `{{campaign}}`.
utm.source	string	max length 200
utm.medium	string	max length 200
utm.campaign	string	max length 200
utm.term	string	max length 200
utm.content	string	max length 200
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

201 response: 201 responseJSON

{
  "id": "utm_01JB4PE5F6G7H8J9K0L1M2N3P4",
  "object": "utm_template",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "name": "string",
  "utm": {
    "source": "string",
    "medium": "string",
    "campaign": "string",
    "term": "string",
    "content": "string"
  },
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

Error codes: invalid_json, invalid_query, missing_header, invalid_cursor, invalid_sort, invalid_expand

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

400 response: missing headerJSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_header",
    "message": "The X-Workspace-Id header is required for session requests.",
    "param": "X-Workspace-Id",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#missing_header"
  }
}

401 response

Error codes: unauthenticated

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

401 response: unauthenticatedJSON

{
  "error": {
    "type": "authentication_error",
    "code": "unauthenticated",
    "message": "The API key is not valid.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#unauthenticated",
    "details": [
      {
        "path": "Authorization",
        "code": "invalid_api_key",
        "message": "No key matches this secret"
      }
    ]
  }
}

403 response

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

403 response: plan limit reachedJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "plan_limit_reached",
    "message": "You have created 2,000 of 2,000 links this billing period. Upgrade or buy a pack to continue.",
    "param": "links_per_month",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "plan_limit_reached",
        "message": "Monthly link quota reached",
        "limit": 2000,
        "used": 2000,
        "resets_at": "2026-12-01T00:00:00.000Z",
        "upgrade_to": "business"
      }
    ]
  }
}

403 response: feature not in planJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "feature_not_in_plan",
    "message": "The public API is available on the Pro plan and above.",
    "param": "api_requests_per_day",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "feature_not_in_plan",
        "message": "Upgrade to Pro",
        "upgrade_to": "pro"
      }
    ]
  }
}

403 response: email verification requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "email_verification_required",
    "message": "Verify your email address to create links.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#email_verification_required"
  }
}

403 response: step up requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "step_up_required",
    "message": "Confirm your password or 2FA code to continue.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#step_up_required"
  }
}

404 response

Unknown id, or the resource belongs to another workspace (never distinguished). Also returned when a session's X-Workspace-Id names a workspace the user is not an active member of.

Error codes: resource_not_found

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

404 response: not foundJSON

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "No link with id lnk_01JB4N8ZK3Q9WXYZ0123456789.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#resource_not_found"
  }
}

409 response

State conflict (slug_taken, domain_already_exists, member_already_exists, invitation_pending, idempotency_in_progress, state_conflict, resource_in_use).

Error codes: slug_taken, domain_already_exists, member_already_exists, invitation_pending, idempotency_in_progress, state_conflict, resource_in_use

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

409 response: slug takenJSON

{
  "error": {
    "type": "conflict_error",
    "code": "slug_taken",
    "message": "The slug \"diwali\" is already in use on crop.sh.",
    "param": "slug",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#slug_taken"
  }
}

422 response

Validation failure (validation_failed, destination_invalid, destination_blocked (details[0].code is policy_violation, with the category, for content-policy blocks), slug_invalid, slug_reserved, slug_not_allowed, handle_not_allowed, title_not_allowed, domain_not_active, domain_proxied, idempotency_key_reused, unsupported_qr_type, qr_unreadable, policy_acceptance_required, …).

Error codes: validation_failed, destination_invalid, destination_blocked, slug_invalid, slug_reserved, domain_not_active, domain_proxied, idempotency_key_reused, unsupported_qr_type, qr_unreadable, policy_acceptance_required

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

422 response: validation failedJSON

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "The request body is invalid.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#validation_failed",
    "details": [
      {
        "path": "destination_url",
        "code": "invalid_string",
        "message": "Must be an absolute http(s) URL"
      }
    ]
  }
}

422 response: destination blockedJSON

{
  "error": {
    "type": "validation_error",
    "code": "destination_blocked",
    "message": "This destination was flagged as unsafe and cannot be shortened.",
    "param": "destination_url",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#destination_blocked"
  }
}

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

429 response: rate limitedJSON

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Daily API quota of 50,000 requests exhausted. Resets at 00:00 UTC.",
    "param": "daily_quota",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/rate-limits"
  }
}

Get a UTM template

GET/utm-templates/{id}

Scope links:read

Parameters

Name	In	Type	Description
idrequired	path	string	Prefixed ULID (`<prefix>_<26 Crockford base32 chars>`).
X-Workspace-Id	header	string	Workspace to act on. Required for session requests on workspace-scoped routes; optional for API keys (must equal the key's workspace, otherwise `403 workspace_mismatch`). For a session, a workspace the user is not an active member of (another tenant, a removed membership, a malformed or unknown id) answers `404 resource_not_found`, never `403`.

Request example

GET /utm-templates/{id}cURL

curl 'https://api.urlcrop.com/v1/utm-templates/lnk_01JB4N8ZK3Q9WXYZ0123456789' \
  -H 'Authorization: Bearer uc_live_…'

Responses

200 response

Template

UtmTemplate schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `utm_template`
workspace_idrequired	string
is_test	boolean
namerequired	string	max length 80
utmrequired	Utm	UTM parameters appended to the destination. Values may contain `{{slug}}`, `{{domain}}`, `{{campaign}}`.
utm.source	string	max length 200
utm.medium	string	max length 200
utm.campaign	string	max length 200
utm.term	string	max length 200
utm.content	string	max length 200
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

200 response: 200 responseJSON

{
  "id": "utm_01JB4PE5F6G7H8J9K0L1M2N3P4",
  "object": "utm_template",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "name": "string",
  "utm": {
    "source": "string",
    "medium": "string",
    "campaign": "string",
    "term": "string",
    "content": "string"
  },
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

Error codes: invalid_json, invalid_query, missing_header, invalid_cursor, invalid_sort, invalid_expand

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

400 response: missing headerJSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_header",
    "message": "The X-Workspace-Id header is required for session requests.",
    "param": "X-Workspace-Id",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#missing_header"
  }
}

401 response

Error codes: unauthenticated

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

401 response: unauthenticatedJSON

{
  "error": {
    "type": "authentication_error",
    "code": "unauthenticated",
    "message": "The API key is not valid.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#unauthenticated",
    "details": [
      {
        "path": "Authorization",
        "code": "invalid_api_key",
        "message": "No key matches this secret"
      }
    ]
  }
}

403 response

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

403 response: plan limit reachedJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "plan_limit_reached",
    "message": "You have created 2,000 of 2,000 links this billing period. Upgrade or buy a pack to continue.",
    "param": "links_per_month",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "plan_limit_reached",
        "message": "Monthly link quota reached",
        "limit": 2000,
        "used": 2000,
        "resets_at": "2026-12-01T00:00:00.000Z",
        "upgrade_to": "business"
      }
    ]
  }
}

403 response: feature not in planJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "feature_not_in_plan",
    "message": "The public API is available on the Pro plan and above.",
    "param": "api_requests_per_day",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "feature_not_in_plan",
        "message": "Upgrade to Pro",
        "upgrade_to": "pro"
      }
    ]
  }
}

403 response: email verification requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "email_verification_required",
    "message": "Verify your email address to create links.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#email_verification_required"
  }
}

403 response: step up requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "step_up_required",
    "message": "Confirm your password or 2FA code to continue.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#step_up_required"
  }
}

404 response

Unknown id, or the resource belongs to another workspace (never distinguished). Also returned when a session's X-Workspace-Id names a workspace the user is not an active member of.

Error codes: resource_not_found

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

404 response: not foundJSON

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "No link with id lnk_01JB4N8ZK3Q9WXYZ0123456789.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#resource_not_found"
  }
}

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

429 response: rate limitedJSON

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Daily API quota of 50,000 requests exhausted. Resets at 00:00 UTC.",
    "param": "daily_quota",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/rate-limits"
  }
}

Update a UTM template

PATCH/utm-templates/{id}

Scope links:write

Parameters

Name	In	Type	Description
idrequired	path	string	Prefixed ULID (`<prefix>_<26 Crockford base32 chars>`).
X-Workspace-Id	header	string	Workspace to act on. Required for session requests on workspace-scoped routes; optional for API keys (must equal the key's workspace, otherwise `403 workspace_mismatch`). For a session, a workspace the user is not an active member of (another tenant, a removed membership, a malformed or unknown id) answers `404 resource_not_found`, never `403`.

Request body application/json

Field	Type	Description
namerequired	string
utmrequired	Utm	UTM parameters appended to the destination. Values may contain `{{slug}}`, `{{domain}}`, `{{campaign}}`.
utm.source	string	max length 200
utm.medium	string	max length 200
utm.campaign	string	max length 200
utm.term	string	max length 200
utm.content	string	max length 200

Request body: Request bodyJSON

{
  "name": "string",
  "utm": {
    "source": "string",
    "medium": "string",
    "campaign": "string",
    "term": "string",
    "content": "string"
  }
}

Example generated from the schema.

Request example

PATCH /utm-templates/{id}cURL

curl -X PATCH 'https://api.urlcrop.com/v1/utm-templates/lnk_01JB4N8ZK3Q9WXYZ0123456789' \
  -H 'Authorization: Bearer uc_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "utm": {
    "source": "string",
    "medium": "string",
    "campaign": "string",
    "term": "string",
    "content": "string"
  }
}'

Responses

200 response

Updated

UtmTemplate schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `utm_template`
workspace_idrequired	string
is_test	boolean
namerequired	string	max length 80
utmrequired	Utm	UTM parameters appended to the destination. Values may contain `{{slug}}`, `{{domain}}`, `{{campaign}}`.
utm.source	string	max length 200
utm.medium	string	max length 200
utm.campaign	string	max length 200
utm.term	string	max length 200
utm.content	string	max length 200
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

200 response: 200 responseJSON

{
  "id": "utm_01JB4PE5F6G7H8J9K0L1M2N3P4",
  "object": "utm_template",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "name": "string",
  "utm": {
    "source": "string",
    "medium": "string",
    "campaign": "string",
    "term": "string",
    "content": "string"
  },
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

Error codes: invalid_json, invalid_query, missing_header, invalid_cursor, invalid_sort, invalid_expand

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

400 response: missing headerJSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_header",
    "message": "The X-Workspace-Id header is required for session requests.",
    "param": "X-Workspace-Id",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#missing_header"
  }
}

401 response

Error codes: unauthenticated

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

401 response: unauthenticatedJSON

{
  "error": {
    "type": "authentication_error",
    "code": "unauthenticated",
    "message": "The API key is not valid.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#unauthenticated",
    "details": [
      {
        "path": "Authorization",
        "code": "invalid_api_key",
        "message": "No key matches this secret"
      }
    ]
  }
}

403 response

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

403 response: plan limit reachedJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "plan_limit_reached",
    "message": "You have created 2,000 of 2,000 links this billing period. Upgrade or buy a pack to continue.",
    "param": "links_per_month",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "plan_limit_reached",
        "message": "Monthly link quota reached",
        "limit": 2000,
        "used": 2000,
        "resets_at": "2026-12-01T00:00:00.000Z",
        "upgrade_to": "business"
      }
    ]
  }
}

403 response: feature not in planJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "feature_not_in_plan",
    "message": "The public API is available on the Pro plan and above.",
    "param": "api_requests_per_day",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "feature_not_in_plan",
        "message": "Upgrade to Pro",
        "upgrade_to": "pro"
      }
    ]
  }
}

403 response: email verification requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "email_verification_required",
    "message": "Verify your email address to create links.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#email_verification_required"
  }
}

403 response: step up requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "step_up_required",
    "message": "Confirm your password or 2FA code to continue.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#step_up_required"
  }
}

404 response

Unknown id, or the resource belongs to another workspace (never distinguished). Also returned when a session's X-Workspace-Id names a workspace the user is not an active member of.

Error codes: resource_not_found

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

404 response: not foundJSON

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "No link with id lnk_01JB4N8ZK3Q9WXYZ0123456789.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#resource_not_found"
  }
}

409 response

State conflict (slug_taken, domain_already_exists, member_already_exists, invitation_pending, idempotency_in_progress, state_conflict, resource_in_use).

Error codes: slug_taken, domain_already_exists, member_already_exists, invitation_pending, idempotency_in_progress, state_conflict, resource_in_use

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

409 response: slug takenJSON

{
  "error": {
    "type": "conflict_error",
    "code": "slug_taken",
    "message": "The slug \"diwali\" is already in use on crop.sh.",
    "param": "slug",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#slug_taken"
  }
}

422 response

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

422 response: validation failedJSON

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "The request body is invalid.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#validation_failed",
    "details": [
      {
        "path": "destination_url",
        "code": "invalid_string",
        "message": "Must be an absolute http(s) URL"
      }
    ]
  }
}

422 response: destination blockedJSON

{
  "error": {
    "type": "validation_error",
    "code": "destination_blocked",
    "message": "This destination was flagged as unsafe and cannot be shortened.",
    "param": "destination_url",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#destination_blocked"
  }
}

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

429 response: rate limitedJSON

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Daily API quota of 50,000 requests exhausted. Resets at 00:00 UTC.",
    "param": "daily_quota",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/rate-limits"
  }
}

Delete a UTM template

DELETE/utm-templates/{id}

Scope links:write

Parameters

Name	In	Type	Description
idrequired	path	string	Prefixed ULID (`<prefix>_<26 Crockford base32 chars>`).
X-Workspace-Id	header	string	Workspace to act on. Required for session requests on workspace-scoped routes; optional for API keys (must equal the key's workspace, otherwise `403 workspace_mismatch`). For a session, a workspace the user is not an active member of (another tenant, a removed membership, a malformed or unknown id) answers `404 resource_not_found`, never `403`.

Request example

DELETE /utm-templates/{id}cURL

curl -X DELETE 'https://api.urlcrop.com/v1/utm-templates/lnk_01JB4N8ZK3Q9WXYZ0123456789' \
  -H 'Authorization: Bearer uc_live_…'

Responses

204 response
Deleted or applied. No body.

400 response

Error codes: invalid_json, invalid_query, missing_header, invalid_cursor, invalid_sort, invalid_expand

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

400 response: missing headerJSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_header",
    "message": "The X-Workspace-Id header is required for session requests.",
    "param": "X-Workspace-Id",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#missing_header"
  }
}

401 response

Error codes: unauthenticated

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

401 response: unauthenticatedJSON

{
  "error": {
    "type": "authentication_error",
    "code": "unauthenticated",
    "message": "The API key is not valid.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#unauthenticated",
    "details": [
      {
        "path": "Authorization",
        "code": "invalid_api_key",
        "message": "No key matches this secret"
      }
    ]
  }
}

403 response

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

403 response: plan limit reachedJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "plan_limit_reached",
    "message": "You have created 2,000 of 2,000 links this billing period. Upgrade or buy a pack to continue.",
    "param": "links_per_month",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "plan_limit_reached",
        "message": "Monthly link quota reached",
        "limit": 2000,
        "used": 2000,
        "resets_at": "2026-12-01T00:00:00.000Z",
        "upgrade_to": "business"
      }
    ]
  }
}

403 response: feature not in planJSON

{
  "error": {
    "type": "plan_limit_error",
    "code": "feature_not_in_plan",
    "message": "The public API is available on the Pro plan and above.",
    "param": "api_requests_per_day",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/pricing",
    "details": [
      {
        "code": "feature_not_in_plan",
        "message": "Upgrade to Pro",
        "upgrade_to": "pro"
      }
    ]
  }
}

403 response: email verification requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "email_verification_required",
    "message": "Verify your email address to create links.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#email_verification_required"
  }
}

403 response: step up requiredJSON

{
  "error": {
    "type": "permission_error",
    "code": "step_up_required",
    "message": "Confirm your password or 2FA code to continue.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#step_up_required"
  }
}

404 response

Unknown id, or the resource belongs to another workspace (never distinguished). Also returned when a session's X-Workspace-Id names a workspace the user is not an active member of.

Error codes: resource_not_found

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

404 response: not foundJSON

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "No link with id lnk_01JB4N8ZK3Q9WXYZ0123456789.",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/errors#resource_not_found"
  }
}

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

Field	Type	Description
errorrequired	object
error.typerequired	string	One of: `invalid_request_error`, `authentication_error`, `permission_error`, `plan_limit_error`, `not_found_error`, `conflict_error`, `validation_error`, `rate_limit_error`, `api_error`
error.coderequired	string	Complete error-code catalogue. `@urlcrop/shared/errors` is tested against this list. `param` on plan_limit_error responses is always a plan limit key.One of: `invalid_json`, `invalid_query`, `missing_header`, `invalid_cursor`, `invalid_sort`, `invalid_expand`, `unauthenticated`, `two_factor_required`, `step_up_required`, `email_verification_required`, `signups_paused`, `insufficient_scope`, `insufficient_role`, `workspace_mismatch`, `wrong_environment`, `workspace_suspended`, `write_blocked_past_due`, `content_policy_hold`, `origin_not_allowed`, `turnstile_failed`, `second_approver_required`, `view_as_read_only`, `support_access_approval_required`, `feature_not_in_plan`, `plan_limit_reached`, `resource_not_found`, `route_not_found`, `slug_taken`, `domain_already_exists`, `member_already_exists`, `invitation_pending`, `idempotency_in_progress`, `state_conflict`, `resource_in_use`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `destination_invalid`, `destination_blocked`, `destination_unreachable`, `slug_invalid`, `slug_reserved`, `domain_not_active`, `domain_proxied`, `idempotency_key_reused`, `unsupported_qr_type`, `qr_unreadable`, `invalid_routing_rule`, `invalid_currency`, `csv_invalid`, `attribution_key_missing`, `policy_acceptance_required`, `rate_limited`, `internal_error`, `upstream_unavailable`, `service_unavailable`, `timeout`
error.messagerequired	string	Human-readable, safe to show to end users.
error.param	string	Field, header or scope the error refers to, when applicable.
error.request_idrequired	string
error.doc_urlrequired	string	Format: uri
error.details	array of object
error.details[].path	string
error.details[].coderequired	string	Zod issue code, `unsupported_in_phase`, a destination safety reason, or a 401 reason.
error.details[].messagerequired	string
error.details[].limit	integer \| null	Plan limit in force (plan_limit_error only; null = unlimited).
error.details[].used	integer	Current usage (plan_limit_error only).
error.details[].resets_at	string	When a periodic limit resets (plan_limit_error only).Format: date-time
error.details[].upgrade_to	string	Plan slug that lifts a plan limit (plan_limit_error only).

429 response: rate limitedJSON

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Daily API quota of 50,000 requests exhausted. Resets at 00:00 UTC.",
    "param": "daily_quota",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://urlcrop.com/docs/api/rate-limits"
  }
}

UTM templates

List UTM templates

Parameters

Request example

Responses

200 response

400 response

401 response

403 response

404 response

429 response

Create a UTM template (Starter+)

Parameters

Request body application/json

Request example

Responses

201 response

400 response

401 response

403 response

404 response

409 response

422 response

429 response

Get a UTM template

Parameters

Request example

Responses

200 response

400 response

401 response

403 response

404 response

429 response

Update a UTM template

Parameters

Request body application/json

Request example

Responses

200 response

400 response

401 response

403 response

404 response

409 response

422 response

429 response

Delete a UTM template

Parameters

Request example

Responses

204 response

400 response

401 response

403 response

404 response

429 response