Campaigns

List campaigns

GET/campaigns

Parameters

Request example

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

Responses

• 200 response

  Campaigns

  CampaignList schema and example

  Field	Type	Description
  datarequired	array of Campaign
  data[].idrequired	string
  data[].objectrequired	string	Value: campaign
  data[].workspace_idrequired	string
  data[].is_testrequired	boolean
  data[].namerequired	string	max length 120
  data[].description	string | null
  data[].statusrequired	string	One of: active, archived
  data[].starts_at	string | null	Format: date-time
  data[].ends_at	string | null	Format: date-time
  data[].utm_template_id	string | null
  data[].link_countrequired	integer
  data[].metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
  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": "cmp_01JB4N0DIWALI2026XXXXXXXXX",
        "object": "campaign",
        "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
        "is_test": false,
        "name": "string",
        "description": "string",
        "status": "active",
        "starts_at": "2026-12-05T10:15:30.000Z",
        "ends_at": "2026-12-05T10:15:30.000Z",
        "utm_template_id": "string",
        "link_count": 0,
        "metadata": {},
        "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
    }
  }

• 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"
    }
  }

• 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"
    }
  }

Create a campaign

POST/campaigns

Parameters

Request body application/json

{
  "name": "string",
  "description": "string",
  "starts_at": "2026-12-05T10:15:30.000Z",
  "ends_at": "2026-12-05T10:15:30.000Z",
  "utm_template_id": "string",
  "metadata": {}
}

Request example

curl -X POST 'https://api.urlcrop.com/v1/campaigns' \
  -H 'Authorization: Bearer uc_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "starts_at": "2026-12-05T10:15:30.000Z",
  "ends_at": "2026-12-05T10:15:30.000Z",
  "utm_template_id": "string",
  "metadata": {}
}'

Responses

• 201 response

  Created

  Campaign schema and example

  Field	Type	Description
  idrequired	string
  objectrequired	string	Value: campaign
  workspace_idrequired	string
  is_testrequired	boolean
  namerequired	string	max length 120
  description	string | null
  statusrequired	string	One of: active, archived
  starts_at	string | null	Format: date-time
  ends_at	string | null	Format: date-time
  utm_template_id	string | null
  link_countrequired	integer
  metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
  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": "cmp_01JB4N0DIWALI2026XXXXXXXXX",
    "object": "campaign",
    "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
    "is_test": false,
    "name": "string",
    "description": "string",
    "status": "active",
    "starts_at": "2026-12-05T10:15:30.000Z",
    "ends_at": "2026-12-05T10:15:30.000Z",
    "utm_template_id": "string",
    "link_count": 0,
    "metadata": {},
    "created_at": "2026-12-05T10:15:30.000Z",
    "updated_at": "2026-12-05T10:15:30.000Z"
  }

• 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"
    }
  }

• 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 campaign

GET/campaigns/{id}

Parameters

Request example

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

Responses

• 200 response

  Campaign

  Campaign schema and example

  Field	Type	Description
  idrequired	string
  objectrequired	string	Value: campaign
  workspace_idrequired	string
  is_testrequired	boolean
  namerequired	string	max length 120
  description	string | null
  statusrequired	string	One of: active, archived
  starts_at	string | null	Format: date-time
  ends_at	string | null	Format: date-time
  utm_template_id	string | null
  link_countrequired	integer
  metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
  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": "cmp_01JB4N0DIWALI2026XXXXXXXXX",
    "object": "campaign",
    "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
    "is_test": false,
    "name": "string",
    "description": "string",
    "status": "active",
    "starts_at": "2026-12-05T10:15:30.000Z",
    "ends_at": "2026-12-05T10:15:30.000Z",
    "utm_template_id": "string",
    "link_count": 0,
    "metadata": {},
    "created_at": "2026-12-05T10:15:30.000Z",
    "updated_at": "2026-12-05T10:15:30.000Z"
  }

• 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"
    }
  }

Update a campaign

PATCH/campaigns/{id}

Parameters

Request body application/json

{
  "name": "string",
  "description": "string",
  "status": "active",
  "starts_at": "2026-12-05T10:15:30.000Z",
  "ends_at": "2026-12-05T10:15:30.000Z",
  "utm_template_id": "string",
  "metadata": {}
}

Request example

curl -X PATCH 'https://api.urlcrop.com/v1/campaigns/lnk_01JB4N8ZK3Q9WXYZ0123456789' \
  -H 'Authorization: Bearer uc_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "status": "active",
  "starts_at": "2026-12-05T10:15:30.000Z",
  "ends_at": "2026-12-05T10:15:30.000Z",
  "utm_template_id": "string",
  "metadata": {}
}'

Responses

• 200 response

  Updated

  Campaign schema and example

  Field	Type	Description
  idrequired	string
  objectrequired	string	Value: campaign
  workspace_idrequired	string
  is_testrequired	boolean
  namerequired	string	max length 120
  description	string | null
  statusrequired	string	One of: active, archived
  starts_at	string | null	Format: date-time
  ends_at	string | null	Format: date-time
  utm_template_id	string | null
  link_countrequired	integer
  metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
  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": "cmp_01JB4N0DIWALI2026XXXXXXXXX",
    "object": "campaign",
    "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
    "is_test": false,
    "name": "string",
    "description": "string",
    "status": "active",
    "starts_at": "2026-12-05T10:15:30.000Z",
    "ends_at": "2026-12-05T10:15:30.000Z",
    "utm_template_id": "string",
    "link_count": 0,
    "metadata": {},
    "created_at": "2026-12-05T10:15:30.000Z",
    "updated_at": "2026-12-05T10:15:30.000Z"
  }

• 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"
    }
  }

• 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"
    }
  }