Skip to content

Public

Public endpoints of the URLCrop API: 9 operations. Credential-free or token-bearing routes. None of them creates or stores a link.

Read the state behind an unsubscribe link

GET/public/email/unsubscribe

  • No credential

No session and no API key; the signed token in t is the credential (valid 400 days). Never changes anything, so mail scanners that open links cannot unsubscribe anyone. An invalid or expired token answers 404 resource_not_found, with the same body whether or not the user exists. Limits: 30 requests per minute per client and 10 per hour per token (429 rate_limited).

Parameters

NameInTypeDescription
trequiredquerystringUnsubscribe token from the email footer or List-Unsubscribe header.

Request example

GET /public/email/unsubscribecURL
curl 'https://api.urlcrop.com/v1/public/email/unsubscribe?t=string'

Responses

  • 200 response

    Category and current state

    UnsubscribeStatus schema and example
    FieldTypeDescription
    categoryrequiredstringOne of: product_tips, usage_alerts
    email_maskedstringThe address with the local part masked (a***@brand.example). Returned by GET only.
    subscribedrequiredbooleanThe category state after the call; always false in the POST response.
    200 response: subscribedJSON
    {
  "category": "product_tips",
  "email_masked": "a***@brand.example",
  "subscribed": true
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

Unsubscribe from one email category

POST/public/email/unsubscribe

  • No credential

RFC 8058 one-click endpoint and the target of the confirm button on the unsubscribe page. The token in t is the credential; the body is List-Unsubscribe=One-Click (mailbox providers) or JSON (the page). Idempotent: repeating the call returns the same result. Turns the category off and records a consent event (one_click or unsubscribe_link; a multipart/form-data one-click body counts as one_click). Turning it back on needs a session (PATCH /me/email-preferences). Same 404 behaviour as GET. Limits: 10 per hour per token; per client 30 per minute, except POSTs carrying a valid token, which get a ceiling of 600 per minute because mailbox providers send from few addresses.

Parameters

NameInTypeDescription
trequiredquerystring

Request body application/json (optional)

Request body: Request bodyJSON
{}
Example generated from the schema.

Request example

POST /public/email/unsubscribecURL
curl -X POST 'https://api.urlcrop.com/v1/public/email/unsubscribe?t=string' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

  • 200 response

    Unsubscribed

    UnsubscribeStatus schema and example
    FieldTypeDescription
    categoryrequiredstringOne of: product_tips, usage_alerts
    email_maskedstringThe address with the local part masked (a***@brand.example). Returned by GET only.
    subscribedrequiredbooleanThe category state after the call; always false in the POST response.
    200 response: doneJSON
    {
  "category": "product_tips",
  "subscribed": false
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

Public cached render by token

GET/public/qr/{token}.{format}

  • No credential

Unguessable render_token from the QR object; the token rotates whenever the code changes, so responses are immutable: Cache-Control: public, max-age=31536000, immutable (vcard and upi codes, whose image carries personal data: public, max-age=3600, s-maxage=86400, and a deleted or erased static one is purged from the edge), ETag, permissive CORS and Cross-Origin-Resource-Policy: cross-origin (embeddable anywhere). wifi codes (the image contains the password) and test-mode codes are never served here: 404 with Cache-Control: no-store. Cloudflare's proxy caches these (Cache Rule on /v1/public/qr/*). A deleted code returns 410 with Cache-Control: no-store. A render that is not ready within 8 s returns 503 with Retry-After: 2. Tokens rotate when the workspace's badge_required changes.

Parameters

NameInTypeDescription
tokenrequiredpathstring
formatrequiredpathstringOne of: png, svg, pdf
sizequeryintegerPNG width in pixels; only the preset sizes are rendered (any other value is 400 invalid_query).One of: 512, 1024, 2048, 4096

Request example

GET /public/qr/{token}.{format}cURL
curl 'https://api.urlcrop.com/v1/public/qr/string.png'

Responses

  • 200 response

    Rendered image or document

    Body schema and example
    200 response: 200 responseJSON
    "string"
    Example generated from the schema.

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 410 response

    The QR code was deleted (Cache-Control: no-store).

  • 429 response

    Burst limit, daily plan quota or endpoint limit exceeded.

    Error codes: rate_limited

    Error schema and example
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 503 response

    The QR render was not ready within 8 s (service_unavailable); a qr.render job is running. Retry after Retry-After seconds (2). Sent with Cache-Control: no-store.

    Error codes: invalid_json, service_unavailable

    Error schema and example
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan slug that lifts a plan limit (plan_limit_error only).
    503 response: 503 responseJSON
    {
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_json",
    "message": "string",
    "param": "string",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://example.com",
    "details": [
      {
        "path": "string",
        "code": "string",
        "message": "string",
        "limit": 0,
        "used": 0,
        "resets_at": "2026-12-05T10:15:30.000Z",
        "upgrade_to": "string"
      }
    ]
  }
}
    Example generated from the schema.

Plans, prices, entitlements and the current no-refund policy version

GET/public/plans

  • No credential

Cached (Cache-Control: public, max-age=300, Vary: CF-IPCountry). Carries the current roadmap phase and the visitor country from CF-IPCountry. All purchases are final; checkout must accept policy_version.

Parameters

NameInTypeDescription
countryquerystringISO country; IN returns INR prices, anything else USD. Omit for both.

Request example

GET /public/planscURL
curl 'https://api.urlcrop.com/v1/public/plans'

Responses

  • 200 response

    Plans

    PlansResponse schema and example
    FieldTypeDescription
    datarequiredarray of Plan
    data[].idrequiredstringOne of: free, starter, pro, business, agency, enterprise
    data[].objectrequiredstringValue: plan
    data[].namerequiredstring
    data[].availabilityrequiredstringWhich roadmap phase sells it.One of: available, coming_soon, contact_sales
    data[].pricesrequiredarray of object
    data[].prices[].idrequiredstring
    data[].prices[].currencyrequiredstringOne of: INR, USD
    data[].prices[].intervalrequiredstringOne of: monthly, annual
    data[].prices[].amountrequiredintegerMinor units. Annual = 10 × monthly.
    data[].entitlementsrequiredobjectnull means unlimited.
    data[].entitlements.links_per_monthinteger | null
    data[].entitlements.qr_codesinteger | null
    data[].entitlements.pagesinteger | null
    data[].entitlements.events_per_monthinteger | null
    data[].entitlements.retention_daysinteger | null
    data[].entitlements.custom_domainsinteger | null
    data[].entitlements.seatsinteger | null
    data[].entitlements.client_workspacesinteger | null
    data[].entitlements.api_requests_per_dayinteger | nullResets 00:00 UTC. null on plans without API access means "not available".
    data[].entitlements.api_burst_per_secondinteger | null
    data[].entitlements.webhooksinteger | null
    data[].entitlements.audit_log_daysinteger | null
    data[].entitlements.badgeboolean
    data[].entitlements.featuresarray of string
    addonsrequiredarray of object
    addons[].idrequiredstringOne of: extra_domain, extra_seat, extra_client_workspace, partners
    addons[].namerequiredstring
    addons[].pricesrequiredarray of Money
    addons[].prices[].amountrequiredintegerInteger minor units (paise, cents). Never a float.
    addons[].prices[].currencyrequiredstringISO 4217 code.One of: INR, USD
    packsrequiredarray of object
    packs[].idrequiredstringOne of: events_100k, api_calls_1m
    packs[].namerequiredstring
    packs[].quantityrequiredinteger
    packs[].validity_daysnumberValue: 365
    packs[].pricesrequiredarray of Money
    packs[].prices[].amountrequiredintegerInteger minor units (paise, cents). Never a float.
    packs[].prices[].currencyrequiredstringISO 4217 code.One of: INR, USD
    policy_versionrequiredstringCurrent version of the Cancellation & No-Refund Policy that checkout must accept.
    policy_urlrequiredstringFormat: uri
    current_phaserequiredintegerCurrent roadmap phase from platform_settings.current_phase (0 until the public launch). Plans and entitlement rows with a later launch phase render as "coming".≥ 0, ≤ 4
    visitor_countryrequiredstring | nullCaller's ISO 3166-1 alpha-2 country from Cloudflare CF-IPCountry; null when unknown (XX), Tor (T1) or absent. Selects the default currency (INR for IN, USD otherwise). Never stored.
    200 response: indiaJSON
    {
  "data": [
    {
      "id": "pro",
      "object": "plan",
      "name": "Pro",
      "availability": "available",
      "prices": [
        {
          "id": "prc_01JB4PJ9K0L1M2N3P4Q5R6S7T8",
          "currency": "INR",
          "interval": "monthly",
          "amount": 149900
        },
        {
          "id": "prc_01JB4PJ9K0L1M2N3P4Q5R6S7T9",
          "currency": "INR",
          "interval": "annual",
          "amount": 1499000
        }
      ],
      "entitlements": {
        "links_per_month": 2000,
        "qr_codes": null,
        "pages": 10,
        "events_per_month": 100000,
        "retention_days": 730,
        "custom_domains": 3,
        "seats": 3,
        "client_workspaces": 0,
        "api_requests_per_day": 50000,
        "api_burst_per_second": 20,
        "webhooks": 5,
        "audit_log_days": 90,
        "badge": false,
        "features": [
          "utm_templates",
          "expiry",
          "password",
          "bulk_csv",
          "smart_routing",
          "deep_links",
          "pixels",
          "public_api",
          "zapier"
        ]
      }
    }
  ],
  "addons": [
    {
      "id": "extra_domain",
      "name": "Extra custom domain",
      "prices": [
        {
          "amount": 29900,
          "currency": "INR"
        }
      ]
    }
  ],
  "packs": [
    {
      "id": "api_calls_1m",
      "name": "1M API calls",
      "quantity": 1000000,
      "validity_days": 365,
      "prices": [
        {
          "amount": 99900,
          "currency": "INR"
        }
      ]
    }
  ],
  "policy_version": "2026-12-01",
  "policy_url": "https://urlcrop.com/legal/refund-policy",
  "current_phase": 1,
  "visitor_country": "IN"
}

  • 429 response

    Burst limit, daily plan quota or endpoint limit exceeded.

    Error codes: rate_limited

    Error schema and example
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

Fetch Open Graph metadata for a URL (Turnstile, nothing stored)

GET/public/link-preview

  • No credential

Powers the free social-preview checker on urlcrop.com. Requires a Cloudflare Turnstile token in the X-Turnstile-Token header (403 turnstile_failed otherwise), 30 requests/min per IP. Server-side fetch with a 5 s timeout and 1 MB cap; private IPs refused. Nothing is created or stored.

Parameters

NameInTypeDescription
urlrequiredquerystring
X-Turnstile-Tokenrequiredheaderstring

Request example

GET /public/link-previewcURL
curl 'https://api.urlcrop.com/v1/public/link-preview?url=https%3A%2F%2Fexample.com'

Responses

  • 200 response

    Metadata

    LinkMetadata schema and example
    FieldTypeDescription
    urlrequiredstringFormat: uri
    titlestring | null
    descriptionstring | null
    image_urlstring | nullFormat: uri
    site_namestring | null
    favicon_urlstring | nullFormat: uri
    200 response: saleJSON
    {
  "url": "https://brand.in/diwali-sale",
  "title": "Diwali Sale 2026 — Brand",
  "description": "Up to 40% off this Diwali.",
  "image_url": "https://brand.in/og/diwali.jpg",
  "site_name": "Brand",
  "favicon_url": "https://brand.in/favicon.ico"
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

Report a link, page or QR code (Turnstile, credential-free)

POST/abuse/reports

  • No credential

Lets anyone report abuse of a URLCrop link, page or QR code; the only credential-free route that stores a record, and it stores a report, never a link. Requires a Cloudflare Turnstile token in X-Turnstile-Token (403 turnstile_failed otherwise) and is limited to 10 reports per hour per IP (429 rate_limited). The reporter email is optional, kept only to send acknowledgement and resolution mail, and removed 90 days after resolution. complaint_type sets the response clock stored as due_at: individual_sexual_content 24 h, court_or_government_order 36 h, other 72 h; is_depicted_person: true forces individual_sexual_content. A duplicate report of the same target from the same email inside 24 h is accepted and linked to the first. The handler validates and enqueues; triage happens in the staff console.

Parameters

NameInTypeDescription
X-Turnstile-Tokenrequiredheaderstring

Request body application/json

FieldTypeDescription
urlrequiredstringThe reported short link, page or QR landing URL (http or https).Format: uri · max length 2048
categoryrequiredstringOne of: phishing, malware, spam, scam, adult, violence, copyright, other, impersonation, gambling, hacking_cracking, weapons_drugs, harassment_blackmail, csam_terror, spam_scam, ip_infringement
complaint_typestringSets the response clock (24 h, 36 h, 72 h).One of: individual_sexual_content, court_or_government_order, other
detailsstringmax length 2000
reporter_emailstringOptional; used only for acknowledgement and resolution mail.Format: email · max length 254
is_depicted_personbooleanThe reporter is the person shown; forces complaint_type to individual_sexual_content.
Request body: phishingJSON
{
  "url": "https://crop.sh/Ab3dE5g",
  "category": "phishing",
  "details": "The page asks for my bank password."
}

Request example

POST /abuse/reportscURL
curl -X POST 'https://api.urlcrop.com/v1/abuse/reports' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://crop.sh/Ab3dE5g",
  "category": "phishing",
  "details": "The page asks for my bank password."
}'

Responses

  • 202 response

    Report accepted for triage.

    AbuseReportAccepted schema and example
    FieldTypeDescription
    idrequiredstring
    202 response: acceptedJSON
    {
  "id": "rep_01JB4N8ZK3Q9WXYZ0123456789"
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 503 response

    The service cannot take the request right now; retry later.

    Error codes: invalid_json

    Error schema and example
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan slug that lifts a plan limit (plan_limit_error only).
    503 response: 503 responseJSON
    {
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_json",
    "message": "string",
    "param": "string",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://example.com",
    "details": [
      {
        "path": "string",
        "code": "string",
        "message": "string",
        "limit": 0,
        "used": 0,
        "resets_at": "2026-12-05T10:15:30.000Z",
        "upgrade_to": "string"
      }
    ]
  }
}
    Example generated from the schema.

Send the claim link for a migrated legacy account (Turnstile, credential-free)

POST/auth/claim/resend

  • No credential

Accounts imported from the old URLCrop platform have no password; their only way in is a claim link (a verification link valid 24 hours). Always answers 202, whether or not the address belongs to an unclaimed legacy account, so it cannot be used to find out which addresses exist. Requires a Turnstile token in X-Turnstile-Token (403 turnstile_failed otherwise); limited to 10 requests per hour per IP and, per address, the same 3 per hour as the verification resend (an over-limit address still gets 202). Completing the link marks the account claimed and stops the reminder emails (day 7, 21, 45).

Parameters

NameInTypeDescription
X-Turnstile-Tokenrequiredheaderstring

Request body application/json

FieldTypeDescription
emailrequiredstringFormat: email · max length 254
Request body: Request bodyJSON
{
  "email": "name@example.com"
}
Example generated from the schema.

Request example

POST /auth/claim/resendcURL
curl -X POST 'https://api.urlcrop.com/v1/auth/claim/resend' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "name@example.com"
}'

Responses

  • 202 response

    Accepted.

    ClaimResendAccepted schema and example
    FieldTypeDescription
    statusrequiredstringValue: accepted
    202 response: 202 responseJSON
    {
  "status": "accepted"
}
    Example generated from the schema.

  • 400 response

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

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

    Error schema and example
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

  • 503 response

    The service cannot take the request right now; retry later.

    Error codes: invalid_json

    Error schema and example
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan slug that lifts a plan limit (plan_limit_error only).
    503 response: 503 responseJSON
    {
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_json",
    "message": "string",
    "param": "string",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://example.com",
    "details": [
      {
        "path": "string",
        "code": "string",
        "message": "string",
        "limit": 0,
        "used": 0,
        "resets_at": "2026-12-05T10:15:30.000Z",
        "upgrade_to": "string"
      }
    ]
  }
}
    Example generated from the schema.

Follow a claim email link

GET/auth/claim

  • No credential

Target of the link in the claim emails. Verifies the signed ticket t (24 hours) and redirects to the verification link; any failure redirects to the sign-in page with claim=expired. Never reveals whether an account exists.

Parameters

NameInTypeDescription
trequiredquerystring

Request example

GET /auth/claimcURL
curl 'https://api.urlcrop.com/v1/auth/claim?t=string'

Responses

  • 302 response

    Redirect to the verification link or the sign-in page.

  • 429 response

    Burst limit, daily plan quota or endpoint limit exceeded.

    Error codes: rate_limited

    Error schema and example
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}

Invitation details for the accept screen

GET/public/invitations/{token}

  • No credential

Parameters

NameInTypeDescription
tokenrequiredpathstring

Request example

GET /public/invitations/{token}cURL
curl 'https://api.urlcrop.com/v1/public/invitations/string'

Responses

  • 200 response

    Invitation summary

    InvitationPublic schema and example
    FieldTypeDescription
    workspace_namerequiredstring
    inviter_namestring | null
    rolerequiredstringOwner has billing and deletion rights; Admin everything else; Editor creates content; Viewer reads; Client (Phase 4) reads a client workspace.One of: owner, admin, editor, viewer, client
    email_hintstringMasked invitee email, e.g. p***a@brand.in.
    expires_atrequiredstringISO 8601 UTC with milliseconds.Format: date-time
    200 response: 200 responseJSON
    {
  "workspace_name": "string",
  "inviter_name": "string",
  "role": "owner",
  "email_hint": "string",
  "expires_at": "2026-12-05T10:15:30.000Z"
}
    Example generated from the schema.

  • 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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
    FieldTypeDescription
    errorrequiredobject
    error.typerequiredstringOne of: invalid_request_error, authentication_error, permission_error, plan_limit_error, not_found_error, conflict_error, validation_error, rate_limit_error, api_error
    error.coderequiredstringComplete 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.messagerequiredstringHuman-readable, safe to show to end users.
    error.paramstringField, header or scope the error refers to, when applicable.
    error.request_idrequiredstring
    error.doc_urlrequiredstringFormat: uri
    error.detailsarray of object
    error.details[].pathstring
    error.details[].coderequiredstringZod issue code, unsupported_in_phase, a destination safety reason, or a 401 reason.
    error.details[].messagerequiredstring
    error.details[].limitinteger | nullPlan limit in force (plan_limit_error only; null = unlimited).
    error.details[].usedintegerCurrent usage (plan_limit_error only).
    error.details[].resets_atstringWhen a periodic limit resets (plan_limit_error only).Format: date-time
    error.details[].upgrade_tostringPlan 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"
  }
}