Pages

Pages endpoints of the URLCrop API: 9 operations. Link-in-bio pages served at `crop.sh/p/slug` or on a custom domain.

List pages

GET/pages

Scope pages:read

Parameters

Name	In	Type	Description
X-Workspace-Id	header	string	Workspace to act on. Required for session requests on workspace-scoped routes; optional for API keys (must equal the key's workspace, otherwise `403 workspace_mismatch`). For a session, a workspace the user is not an active member of (another tenant, a removed membership, a malformed or unknown id) answers `404 resource_not_found`, never `403`.
cursor	query	string	Opaque cursor from `pagination.next_cursor`.
limit	query	integer	Page size (1–100).
sort	query	string	Sort field; prefix with `-` for descending. Allowed fields are listed per resource (`x-sortable`).
type	query	string
status	query	string	One of: `draft`, `published`, `unpublished`
q	query	string

Request example

GET /pagescURL

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

Responses

200 response

Pages

PageList schema and example

Field	Type	Description
datarequired	array of Page
data[].idrequired	string
data[].objectrequired	string	Value: `page`
data[].workspace_idrequired	string
data[].is_testrequired	boolean
data[].typerequired	string	v1 ships `bio`; `landing`, `lead_form` and `vcard` follow in Phase 2.Value: `bio`
data[].titlerequired	string	max length 120
data[].handlerequired	string	Own namespace under `/p/`; 3–30 chars of `[a-z0-9_-]`, not on the reserved list. Handles are unique per domain.
data[].domainrequired	string
data[].urlrequired	string	Format: uri
data[].statusrequired	string	Only `published` pages are served; draft and unpublished answer `404`.One of: `draft`, `published`, `unpublished`
data[].themerequired	string	Preset key.One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
data[].theme_overridesrequired	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
data[].theme_overrides.bg	string
data[].theme_overrides.button_bg	string
data[].profilerequired	PageProfile
data[].profile.namerequired	string	max length 80
data[].profile.biorequired	string	max length 300
data[].profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
data[].profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
data[].seorequired	PageSeo
data[].seo.title	string	max length 120
data[].seo.description	string	max length 300
data[].seo.og_image_asset_key	string	max length 255
data[].seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
data[].seo.noindexrequired	boolean
data[].blocksrequired	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50
data[].show_badgerequired	boolean	"Made with URLCrop" badge; forced on while the plan has `badge_required`.
data[].policy_holdrequired	boolean	True while the page is on content-policy hold: it is not served and publishing answers `403 content_policy_hold`.
data[].published_at	string \| null	Format: date-time
data[].metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
data[].created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
data[].updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
paginationrequired	Pagination
pagination.limitrequired	integer
pagination.has_morerequired	boolean
pagination.next_cursorrequired	string \| null	Pass as `cursor` to fetch the next page. `null` on the last page.
pagination.total	integer	Only with `include_total=true`; estimated above 10,000.

200 response: 200 responseJSON

{
  "data": [
    {
      "id": "pg_01JB4PB2C3D4E5F6G7H8J9K0L1",
      "object": "page",
      "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
      "is_test": false,
      "type": "bio",
      "title": "string",
      "handle": "priya",
      "domain": "crop.sh",
      "url": "https://crop.sh/p/priya",
      "status": "draft",
      "theme": "paper",
      "theme_overrides": {
        "bg": "string",
        "button_bg": "string"
      },
      "profile": {
        "name": "string",
        "bio": "string",
        "avatar_asset_key": "string",
        "avatar_src": "string"
      },
      "seo": {
        "title": "string",
        "description": "string",
        "og_image_asset_key": "string",
        "og_image_src": "string",
        "noindex": false
      },
      "blocks": [
        {
          "id": null,
          "position": null,
          "is_visible": null,
          "clicks": null,
          "type": null,
          "schema_version": null,
          "label": null,
          "url": null,
          "link_id": null
        }
      ],
      "show_badge": false,
      "policy_hold": false,
      "published_at": "2026-12-05T10:15:30.000Z",
      "metadata": {},
      "created_at": "2026-12-05T10:15:30.000Z",
      "updated_at": "2026-12-05T10:15:30.000Z"
    }
  ],
  "pagination": {
    "limit": 0,
    "has_more": false,
    "next_cursor": "string",
    "total": 0
  }
}

Example generated from the schema.

400 response

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

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

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

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

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

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

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Create a page (draft)

POST/pages

Scope pages:write

Counts toward the pages quota (403 plan_limit_reached, param: pages_total); its link buttons do not count toward links_per_month. Requires a verified email. A handle already used on the domain → 409 state_conflict (param: handle); a reserved handle → 422 validation_failed. Public URL https://crop.sh/p/{handle}.

Parameters

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

Request body application/json

Field	Type	Description
typerequired	string	Value: `bio`
titlerequired	string	max length 120
handlerequired	string
domain	string	Hostname of a verified custom domain owned by the workspace (needs `custom_domains` above 0, else `403 feature_not_in_plan`, `param: custom_domains`; an unverified or foreign domain is `422 validation_failed`, `param: domain`). Omit for the shared domain.
show_badge	boolean	Show the "Made with URLCrop" badge (default false). Plans that require the badge show it regardless of this value.
theme	string	One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
theme_overrides	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
theme_overrides.bg	string
theme_overrides.button_bg	string
profile	PageProfile
profile.namerequired	string	max length 80
profile.biorequired	string	max length 300
profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
seo	PageSeo
seo.title	string	max length 120
seo.description	string	max length 300
seo.og_image_asset_key	string	max length 255
seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
seo.noindexrequired	boolean
blocks	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50
metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20

Request body: bioJSON

{
  "type": "bio",
  "title": "Priya Sharma",
  "handle": "priya",
  "theme": "violet",
  "profile": {
    "name": "Priya Sharma",
    "bio": "Fashion and lifestyle, Pune"
  },
  "blocks": [
    {
      "type": "link_button",
      "schema_version": 1,
      "label": "Shop my Diwali edit",
      "url": "https://brand.in/diwali-sale?ref=priya"
    },
    {
      "type": "social_row",
      "schema_version": 1,
      "items": [
        {
          "network": "instagram",
          "url": "https://instagram.com/priya.sharma"
        }
      ]
    }
  ]
}

Request example

POST /pagescURL

curl -X POST 'https://api.urlcrop.com/v1/pages' \
  -H 'Authorization: Bearer uc_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "bio",
  "title": "Priya Sharma",
  "handle": "priya",
  "theme": "violet",
  "profile": {
    "name": "Priya Sharma",
    "bio": "Fashion and lifestyle, Pune"
  },
  "blocks": [
    {
      "type": "link_button",
      "schema_version": 1,
      "label": "Shop my Diwali edit",
      "url": "https://brand.in/diwali-sale?ref=priya"
    },
    {
      "type": "social_row",
      "schema_version": 1,
      "items": [
        {
          "network": "instagram",
          "url": "https://instagram.com/priya.sharma"
        }
      ]
    }
  ]
}'

Responses

201 response

Draft created

Page schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `page`
workspace_idrequired	string
is_testrequired	boolean
typerequired	string	v1 ships `bio`; `landing`, `lead_form` and `vcard` follow in Phase 2.Value: `bio`
titlerequired	string	max length 120
handlerequired	string	Own namespace under `/p/`; 3–30 chars of `[a-z0-9_-]`, not on the reserved list. Handles are unique per domain.
domainrequired	string
urlrequired	string	Format: uri
statusrequired	string	Only `published` pages are served; draft and unpublished answer `404`.One of: `draft`, `published`, `unpublished`
themerequired	string	Preset key.One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
theme_overridesrequired	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
theme_overrides.bg	string
theme_overrides.button_bg	string
profilerequired	PageProfile
profile.namerequired	string	max length 80
profile.biorequired	string	max length 300
profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
seorequired	PageSeo
seo.title	string	max length 120
seo.description	string	max length 300
seo.og_image_asset_key	string	max length 255
seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
seo.noindexrequired	boolean
blocksrequired	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50
show_badgerequired	boolean	"Made with URLCrop" badge; forced on while the plan has `badge_required`.
policy_holdrequired	boolean	True while the page is on content-policy hold: it is not served and publishing answers `403 content_policy_hold`.
published_at	string \| null	Format: date-time
metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

201 response: 201 responseJSON

{
  "id": "pg_01JB4PB2C3D4E5F6G7H8J9K0L1",
  "object": "page",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "type": "bio",
  "title": "string",
  "handle": "priya",
  "domain": "crop.sh",
  "url": "https://crop.sh/p/priya",
  "status": "draft",
  "theme": "paper",
  "theme_overrides": {
    "bg": "string",
    "button_bg": "string"
  },
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar_asset_key": "string",
    "avatar_src": "string"
  },
  "seo": {
    "title": "string",
    "description": "string",
    "og_image_asset_key": "string",
    "og_image_src": "string",
    "noindex": false
  },
  "blocks": [
    {
      "id": "blk_01JB4PC3D4E5F6G7H8J9K0L1M2",
      "position": 0,
      "is_visible": true,
      "clicks": 0,
      "type": "link_button",
      "schema_version": 1,
      "label": "string",
      "url": "https://example.com",
      "link_id": "string"
    }
  ],
  "show_badge": false,
  "policy_hold": false,
  "published_at": "2026-12-05T10:15:30.000Z",
  "metadata": {},
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

409 response

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

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

Error schema and example

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

409 response: slug takenJSON

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

422 response

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

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

Error schema and example

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

422 response: validation failedJSON

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

422 response: destination blockedJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Get a page with its blocks

GET/pages/{id}

Scope pages:read

Parameters

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

Request example

GET /pages/{id}cURL

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

Responses

200 response

Page

Page schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `page`
workspace_idrequired	string
is_testrequired	boolean
typerequired	string	v1 ships `bio`; `landing`, `lead_form` and `vcard` follow in Phase 2.Value: `bio`
titlerequired	string	max length 120
handlerequired	string	Own namespace under `/p/`; 3–30 chars of `[a-z0-9_-]`, not on the reserved list. Handles are unique per domain.
domainrequired	string
urlrequired	string	Format: uri
statusrequired	string	Only `published` pages are served; draft and unpublished answer `404`.One of: `draft`, `published`, `unpublished`
themerequired	string	Preset key.One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
theme_overridesrequired	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
theme_overrides.bg	string
theme_overrides.button_bg	string
profilerequired	PageProfile
profile.namerequired	string	max length 80
profile.biorequired	string	max length 300
profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
seorequired	PageSeo
seo.title	string	max length 120
seo.description	string	max length 300
seo.og_image_asset_key	string	max length 255
seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
seo.noindexrequired	boolean
blocksrequired	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50
show_badgerequired	boolean	"Made with URLCrop" badge; forced on while the plan has `badge_required`.
policy_holdrequired	boolean	True while the page is on content-policy hold: it is not served and publishing answers `403 content_policy_hold`.
published_at	string \| null	Format: date-time
metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

200 response: 200 responseJSON

{
  "id": "pg_01JB4PB2C3D4E5F6G7H8J9K0L1",
  "object": "page",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "type": "bio",
  "title": "string",
  "handle": "priya",
  "domain": "crop.sh",
  "url": "https://crop.sh/p/priya",
  "status": "draft",
  "theme": "paper",
  "theme_overrides": {
    "bg": "string",
    "button_bg": "string"
  },
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar_asset_key": "string",
    "avatar_src": "string"
  },
  "seo": {
    "title": "string",
    "description": "string",
    "og_image_asset_key": "string",
    "og_image_src": "string",
    "noindex": false
  },
  "blocks": [
    {
      "id": "blk_01JB4PC3D4E5F6G7H8J9K0L1M2",
      "position": 0,
      "is_visible": true,
      "clicks": 0,
      "type": "link_button",
      "schema_version": 1,
      "label": "string",
      "url": "https://example.com",
      "link_id": "string"
    }
  ],
  "show_badge": false,
  "policy_hold": false,
  "published_at": "2026-12-05T10:15:30.000Z",
  "metadata": {},
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Update page settings (not blocks)

PATCH/pages/{id}

Scope pages:write

Parameters

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

Request body application/json

Field	Type	Description
title	string	max length 120
handle	string
domain	string	Hostname of a verified custom domain owned by the workspace (same rules as on create). A published page cannot change domain.
show_badge	boolean	Show the "Made with URLCrop" badge. Plans that require the badge show it regardless of this value.
theme	string	One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
theme_overrides	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
theme_overrides.bg	string
theme_overrides.button_bg	string
profile	PageProfile
profile.namerequired	string	max length 80
profile.biorequired	string	max length 300
profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
seo	PageSeo
seo.title	string	max length 120
seo.description	string	max length 300
seo.og_image_asset_key	string	max length 255
seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
seo.noindexrequired	boolean
metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20

Request body: Request bodyJSON

{
  "title": "string",
  "handle": "string",
  "domain": "string",
  "show_badge": false,
  "theme": "paper",
  "theme_overrides": {
    "bg": "string",
    "button_bg": "string"
  },
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar_asset_key": "string",
    "avatar_src": "string"
  },
  "seo": {
    "title": "string",
    "description": "string",
    "og_image_asset_key": "string",
    "og_image_src": "string",
    "noindex": false
  },
  "metadata": {}
}

Example generated from the schema.

Request example

PATCH /pages/{id}cURL

curl -X PATCH 'https://api.urlcrop.com/v1/pages/lnk_01JB4N8ZK3Q9WXYZ0123456789' \
  -H 'Authorization: Bearer uc_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "string",
  "handle": "string",
  "domain": "string",
  "show_badge": false,
  "theme": "paper",
  "theme_overrides": {
    "bg": "string",
    "button_bg": "string"
  },
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar_asset_key": "string",
    "avatar_src": "string"
  },
  "seo": {
    "title": "string",
    "description": "string",
    "og_image_asset_key": "string",
    "og_image_src": "string",
    "noindex": false
  },
  "metadata": {}
}'

Responses

200 response

Updated

Page schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `page`
workspace_idrequired	string
is_testrequired	boolean
typerequired	string	v1 ships `bio`; `landing`, `lead_form` and `vcard` follow in Phase 2.Value: `bio`
titlerequired	string	max length 120
handlerequired	string	Own namespace under `/p/`; 3–30 chars of `[a-z0-9_-]`, not on the reserved list. Handles are unique per domain.
domainrequired	string
urlrequired	string	Format: uri
statusrequired	string	Only `published` pages are served; draft and unpublished answer `404`.One of: `draft`, `published`, `unpublished`
themerequired	string	Preset key.One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
theme_overridesrequired	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
theme_overrides.bg	string
theme_overrides.button_bg	string
profilerequired	PageProfile
profile.namerequired	string	max length 80
profile.biorequired	string	max length 300
profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
seorequired	PageSeo
seo.title	string	max length 120
seo.description	string	max length 300
seo.og_image_asset_key	string	max length 255
seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
seo.noindexrequired	boolean
blocksrequired	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50
show_badgerequired	boolean	"Made with URLCrop" badge; forced on while the plan has `badge_required`.
policy_holdrequired	boolean	True while the page is on content-policy hold: it is not served and publishing answers `403 content_policy_hold`.
published_at	string \| null	Format: date-time
metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

200 response: 200 responseJSON

{
  "id": "pg_01JB4PB2C3D4E5F6G7H8J9K0L1",
  "object": "page",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "type": "bio",
  "title": "string",
  "handle": "priya",
  "domain": "crop.sh",
  "url": "https://crop.sh/p/priya",
  "status": "draft",
  "theme": "paper",
  "theme_overrides": {
    "bg": "string",
    "button_bg": "string"
  },
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar_asset_key": "string",
    "avatar_src": "string"
  },
  "seo": {
    "title": "string",
    "description": "string",
    "og_image_asset_key": "string",
    "og_image_src": "string",
    "noindex": false
  },
  "blocks": [
    {
      "id": "blk_01JB4PC3D4E5F6G7H8J9K0L1M2",
      "position": 0,
      "is_visible": true,
      "clicks": 0,
      "type": "link_button",
      "schema_version": 1,
      "label": "string",
      "url": "https://example.com",
      "link_id": "string"
    }
  ],
  "show_badge": false,
  "policy_hold": false,
  "published_at": "2026-12-05T10:15:30.000Z",
  "metadata": {},
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

409 response

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

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

Error schema and example

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

409 response: slug takenJSON

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

422 response

Error schema and example

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

422 response: validation failedJSON

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

422 response: destination blockedJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Delete a page

DELETE/pages/{id}

Scope pages:write

Soft-deletes the page and frees its pages_total slot; the public URL answers 404.

Parameters

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

Request example

DELETE /pages/{id}cURL

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

Responses

204 response
Deleted or applied. No body.

400 response

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Replace the ordered block list (≤ 50)

PUT/pages/{id}/blocks

Scope pages:write

More than 50 blocks → 422 validation_failed; a block type outside the seven v1 types → 422 unsupported_block_type. Blocks keep their id to preserve analytics.

Parameters

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

Request body application/json

Field	Type	Description
blocksrequired	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50

Request body: Request bodyJSON

{
  "blocks": [
    {
      "id": "blk_01JB4PC3D4E5F6G7H8J9K0L1M2",
      "position": 0,
      "is_visible": true,
      "clicks": 0,
      "type": "link_button",
      "schema_version": 1,
      "label": "string",
      "url": "https://example.com",
      "link_id": "string"
    }
  ]
}

Example generated from the schema.

Request example

PUT /pages/{id}/blockscURL

curl -X PUT 'https://api.urlcrop.com/v1/pages/lnk_01JB4N8ZK3Q9WXYZ0123456789/blocks' \
  -H 'Authorization: Bearer uc_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "blocks": [
    {
      "id": "blk_01JB4PC3D4E5F6G7H8J9K0L1M2",
      "position": 0,
      "is_visible": true,
      "clicks": 0,
      "type": "link_button",
      "schema_version": 1,
      "label": "string",
      "url": "https://example.com",
      "link_id": "string"
    }
  ]
}'

Responses

200 response

Page with new blocks

Page schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `page`
workspace_idrequired	string
is_testrequired	boolean
typerequired	string	v1 ships `bio`; `landing`, `lead_form` and `vcard` follow in Phase 2.Value: `bio`
titlerequired	string	max length 120
handlerequired	string	Own namespace under `/p/`; 3–30 chars of `[a-z0-9_-]`, not on the reserved list. Handles are unique per domain.
domainrequired	string
urlrequired	string	Format: uri
statusrequired	string	Only `published` pages are served; draft and unpublished answer `404`.One of: `draft`, `published`, `unpublished`
themerequired	string	Preset key.One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
theme_overridesrequired	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
theme_overrides.bg	string
theme_overrides.button_bg	string
profilerequired	PageProfile
profile.namerequired	string	max length 80
profile.biorequired	string	max length 300
profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
seorequired	PageSeo
seo.title	string	max length 120
seo.description	string	max length 300
seo.og_image_asset_key	string	max length 255
seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
seo.noindexrequired	boolean
blocksrequired	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50
show_badgerequired	boolean	"Made with URLCrop" badge; forced on while the plan has `badge_required`.
policy_holdrequired	boolean	True while the page is on content-policy hold: it is not served and publishing answers `403 content_policy_hold`.
published_at	string \| null	Format: date-time
metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

200 response: 200 responseJSON

{
  "id": "pg_01JB4PB2C3D4E5F6G7H8J9K0L1",
  "object": "page",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "type": "bio",
  "title": "string",
  "handle": "priya",
  "domain": "crop.sh",
  "url": "https://crop.sh/p/priya",
  "status": "draft",
  "theme": "paper",
  "theme_overrides": {
    "bg": "string",
    "button_bg": "string"
  },
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar_asset_key": "string",
    "avatar_src": "string"
  },
  "seo": {
    "title": "string",
    "description": "string",
    "og_image_asset_key": "string",
    "og_image_src": "string",
    "noindex": false
  },
  "blocks": [
    {
      "id": "blk_01JB4PC3D4E5F6G7H8J9K0L1M2",
      "position": 0,
      "is_visible": true,
      "clicks": 0,
      "type": "link_button",
      "schema_version": 1,
      "label": "string",
      "url": "https://example.com",
      "link_id": "string"
    }
  ],
  "show_badge": false,
  "policy_hold": false,
  "published_at": "2026-12-05T10:15:30.000Z",
  "metadata": {},
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

422 response

Error schema and example

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

422 response: validation failedJSON

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

422 response: destination blockedJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Publish a page

POST/pages/{id}/publish

Scope pages:write

Every link button is safety-scanned and gets a tracked short link (created_via: page, not counted in links_per_month); the page then serves at https://crop.sh/p/{handle}. Publishing a live page again rebuilds the snapshot and bumps the revision. Image assets are resolved to public paths at publish (422 validation_failed naming the block if one no longer exists). 409 state_conflict only for test-mode pages.

Parameters

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

Request example

POST /pages/{id}/publishcURL

curl -X POST 'https://api.urlcrop.com/v1/pages/lnk_01JB4N8ZK3Q9WXYZ0123456789/publish' \
  -H 'Authorization: Bearer uc_live_…'

Responses

200 response

Published

Page schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `page`
workspace_idrequired	string
is_testrequired	boolean
typerequired	string	v1 ships `bio`; `landing`, `lead_form` and `vcard` follow in Phase 2.Value: `bio`
titlerequired	string	max length 120
handlerequired	string	Own namespace under `/p/`; 3–30 chars of `[a-z0-9_-]`, not on the reserved list. Handles are unique per domain.
domainrequired	string
urlrequired	string	Format: uri
statusrequired	string	Only `published` pages are served; draft and unpublished answer `404`.One of: `draft`, `published`, `unpublished`
themerequired	string	Preset key.One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
theme_overridesrequired	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
theme_overrides.bg	string
theme_overrides.button_bg	string
profilerequired	PageProfile
profile.namerequired	string	max length 80
profile.biorequired	string	max length 300
profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
seorequired	PageSeo
seo.title	string	max length 120
seo.description	string	max length 300
seo.og_image_asset_key	string	max length 255
seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
seo.noindexrequired	boolean
blocksrequired	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50
show_badgerequired	boolean	"Made with URLCrop" badge; forced on while the plan has `badge_required`.
policy_holdrequired	boolean	True while the page is on content-policy hold: it is not served and publishing answers `403 content_policy_hold`.
published_at	string \| null	Format: date-time
metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

200 response: 200 responseJSON

{
  "id": "pg_01JB4PB2C3D4E5F6G7H8J9K0L1",
  "object": "page",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "type": "bio",
  "title": "string",
  "handle": "priya",
  "domain": "crop.sh",
  "url": "https://crop.sh/p/priya",
  "status": "draft",
  "theme": "paper",
  "theme_overrides": {
    "bg": "string",
    "button_bg": "string"
  },
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar_asset_key": "string",
    "avatar_src": "string"
  },
  "seo": {
    "title": "string",
    "description": "string",
    "og_image_asset_key": "string",
    "og_image_src": "string",
    "noindex": false
  },
  "blocks": [
    {
      "id": "blk_01JB4PC3D4E5F6G7H8J9K0L1M2",
      "position": 0,
      "is_visible": true,
      "clicks": 0,
      "type": "link_button",
      "schema_version": 1,
      "label": "string",
      "url": "https://example.com",
      "link_id": "string"
    }
  ],
  "show_badge": false,
  "policy_hold": false,
  "published_at": "2026-12-05T10:15:30.000Z",
  "metadata": {},
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

409 response

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

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

Error schema and example

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

409 response: slug takenJSON

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

422 response

Error schema and example

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

422 response: validation failedJSON

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

422 response: destination blockedJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Unpublish a page

POST/pages/{id}/unpublish

Scope pages:write

The public URL answers 404 from the next cache refresh. The page can be published again.

Parameters

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

Request example

POST /pages/{id}/unpublishcURL

curl -X POST 'https://api.urlcrop.com/v1/pages/lnk_01JB4N8ZK3Q9WXYZ0123456789/unpublish' \
  -H 'Authorization: Bearer uc_live_…'

Responses

200 response

Unpublished

Page schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `page`
workspace_idrequired	string
is_testrequired	boolean
typerequired	string	v1 ships `bio`; `landing`, `lead_form` and `vcard` follow in Phase 2.Value: `bio`
titlerequired	string	max length 120
handlerequired	string	Own namespace under `/p/`; 3–30 chars of `[a-z0-9_-]`, not on the reserved list. Handles are unique per domain.
domainrequired	string
urlrequired	string	Format: uri
statusrequired	string	Only `published` pages are served; draft and unpublished answer `404`.One of: `draft`, `published`, `unpublished`
themerequired	string	Preset key.One of: `paper`, `ink`, `violet`, `saffron`, `mint`, `night`, `candy`, `mono`
theme_overridesrequired	PageThemeOverrides	Colour overrides on the preset. An override that drops the button label below 4.5:1 contrast → `422 validation_failed`.
theme_overrides.bg	string
theme_overrides.button_bg	string
profilerequired	PageProfile
profile.namerequired	string	max length 80
profile.biorequired	string	max length 300
profile.avatar_asset_key	string	Key of an asset uploaded with `purpose: avatar`.max length 255
profile.avatar_src	string \| null	Public path of the avatar, resolved on read; `null` when the asset is gone.
seorequired	PageSeo
seo.title	string	max length 120
seo.description	string	max length 300
seo.og_image_asset_key	string	max length 255
seo.og_image_src	string \| null	Public path of the OG image, resolved on read; `null` when the asset is gone.
seo.noindexrequired	boolean
blocksrequired	array of PageBlockLinkButton \| PageBlockSocialRow \| PageBlockHeading \| PageBlockText \| PageBlockImage \| PageBlockDivider \| PageBlockEmbed	max items 50
show_badgerequired	boolean	"Made with URLCrop" badge; forced on while the plan has `badge_required`.
policy_holdrequired	boolean	True while the page is on content-policy hold: it is not served and publishing answers `403 content_policy_hold`.
published_at	string \| null	Format: date-time
metadata	Metadata	Up to 20 keys (≤ 40 chars) with string values (≤ 500 chars). Stored verbatim.max keys 20
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
updated_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

200 response: 200 responseJSON

{
  "id": "pg_01JB4PB2C3D4E5F6G7H8J9K0L1",
  "object": "page",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "type": "bio",
  "title": "string",
  "handle": "priya",
  "domain": "crop.sh",
  "url": "https://crop.sh/p/priya",
  "status": "draft",
  "theme": "paper",
  "theme_overrides": {
    "bg": "string",
    "button_bg": "string"
  },
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar_asset_key": "string",
    "avatar_src": "string"
  },
  "seo": {
    "title": "string",
    "description": "string",
    "og_image_asset_key": "string",
    "og_image_src": "string",
    "noindex": false
  },
  "blocks": [
    {
      "id": "blk_01JB4PC3D4E5F6G7H8J9K0L1M2",
      "position": 0,
      "is_visible": true,
      "clicks": 0,
      "type": "link_button",
      "schema_version": 1,
      "label": "string",
      "url": "https://example.com",
      "link_id": "string"
    }
  ],
  "show_badge": false,
  "policy_hold": false,
  "published_at": "2026-12-05T10:15:30.000Z",
  "metadata": {},
  "created_at": "2026-12-05T10:15:30.000Z",
  "updated_at": "2026-12-05T10:15:30.000Z"
}

Example generated from the schema.

400 response

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Views, unique visitors and block clicks for one page

GET/pages/{id}/stats

Scope insights:read

Parameters

Name	In	Type	Description
idrequired	path	string	Prefixed ULID (`<prefix>_<26 Crockford base32 chars>`).
X-Workspace-Id	header	string	Workspace to act on. Required for session requests on workspace-scoped routes; optional for API keys (must equal the key's workspace, otherwise `403 workspace_mismatch`). For a session, a workspace the user is not an active member of (another tenant, a removed membership, a malformed or unknown id) answers `404 resource_not_found`, never `403`.
from	query	string	Start of the period (inclusive). `YYYY-MM-DD` or RFC 3339. Default 30 days ago.
to	query	string	End of the period (inclusive). Default now.
timezone	query	string	IANA timezone for bucketing. Default is the workspace timezone.
include_bots	query	boolean	When `true`, flagged bot events are added into click, scan and view counts (the rollups' `bots` column). Default `false` excludes them. `unique_visitors` never includes bots.

Request example

GET /pages/{id}/statscURL

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

Responses

200 response

Stats

PageStats schema and example

Field	Type	Description
objectrequired	string	Value: `stats`
subject_id	string	Prefixed ULID (`<prefix>_<26 Crockford base32 chars>`).
periodrequired	object
period.fromrequired	string	ISO 8601 UTC with milliseconds.Format: date-time
period.torequired	string	ISO 8601 UTC with milliseconds.Format: date-time
period.timezonerequired	string
truncated_to_retention	boolean	True when `period.from` was moved forward to the plan's `analytics_retention_days` window (also sent as `X-URLCrop-Truncated retention`).
totalsrequired	object
totals.clicks	integer
totals.scans	integer
totals.views	integer
totals.unique_visitors	integer	Sum of daily unique visitors over the period ("unique visitors (daily)").
totals.over_quota_events	integer	Events beyond the monthly event quota in the UTC months overlapping the period. Counted, but stored without detail, so they are not in `timeseries`, `top` or the other totals.
totals.conversions	integer	Phase 2.
totals.revenue	Money
totals.revenue.amountrequired	integer	Integer minor units (paise, cents). Never a float.
totals.revenue.currencyrequired	string	ISO 4217 code.One of: `INR`, `USD`
timeseriesrequired	array of object
timeseries[].daterequired	string	Format: date
timeseries[].clicks	integer
timeseries[].scans	integer
timeseries[].views	integer
timeseries[].unique_visitors	integer
toprequired	object
top.countries	array of BreakdownRow
top.countries[].keyrequired	string	Dimension value (ISO country code, device class, referrer host, link id…).
top.countries[].label	string
top.countries[].valuerequired	number
top.countries[].share	number	Fraction of the total (0–1).
top.devices	array of BreakdownRow
top.devices[].keyrequired	string	Dimension value (ISO country code, device class, referrer host, link id…).
top.devices[].label	string
top.devices[].valuerequired	number
top.devices[].share	number	Fraction of the total (0–1).
top.referrers	array of BreakdownRow
top.referrers[].keyrequired	string	Dimension value (ISO country code, device class, referrer host, link id…).
top.referrers[].label	string
top.referrers[].valuerequired	number
top.referrers[].share	number	Fraction of the total (0–1).
blocksrequired	array of object	Clicks per link button in the period.
blocks[].block_idrequired	string
blocks[].clicksrequired	integer
bots_flaggedrequired	integer	Views and clicks in the period that were flagged as bots (excluded from the totals).

200 response: 200 responseJSON

{
  "object": "stats",
  "subject_id": "lnk_01JB4N8ZK3Q9WXYZ0123456789",
  "period": {
    "from": "2026-12-05T10:15:30.000Z",
    "to": "2026-12-05T10:15:30.000Z",
    "timezone": "string"
  },
  "truncated_to_retention": false,
  "totals": {
    "clicks": 0,
    "scans": 0,
    "views": 0,
    "unique_visitors": 0,
    "over_quota_events": 0,
    "conversions": 0,
    "revenue": {
      "amount": 149900,
      "currency": "INR"
    }
  },
  "timeseries": [
    {
      "date": "2026-12-05",
      "clicks": 0,
      "scans": 0,
      "views": 0,
      "unique_visitors": 0
    }
  ],
  "top": {
    "countries": [
      {
        "key": "IN",
        "label": "India",
        "value": 0,
        "share": 0
      }
    ],
    "devices": [
      {
        "key": "IN",
        "label": "India",
        "value": 0,
        "share": 0
      }
    ],
    "referrers": [
      {
        "key": "IN",
        "label": "India",
        "value": 0,
        "share": 0
      }
    ]
  },
  "blocks": [
    {
      "block_id": "string",
      "clicks": 0
    }
  ],
  "bots_flagged": 0
}

Example generated from the schema.

304 response
The If-None-Match ETag matches; no body. Sent for cacheable aggregate reads (Cache-Control: private, max-age=30, weak ETag).

400 response

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

Error schema and example

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

400 response: missing headerJSON

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

401 response

Error codes: unauthenticated

Error schema and example

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

401 response: unauthenticatedJSON

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

403 response

Error schema and example

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

403 response: plan limit reachedJSON

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

403 response: feature not in planJSON

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

403 response: email verification requiredJSON

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

403 response: step up requiredJSON

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

404 response

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

Error codes: resource_not_found

Error schema and example

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

404 response: not foundJSON

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

429 response

Burst limit, daily plan quota or endpoint limit exceeded.

Error codes: rate_limited

Error schema and example

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

429 response: rate limitedJSON

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

Pages

List pages

Parameters

Request example

Responses

200 response

400 response

401 response

403 response

404 response

429 response

Create a page (draft)

Parameters

Request body application/json

Request example

Responses

201 response

400 response

401 response

403 response

404 response

409 response

422 response

429 response

Get a page with its blocks

Parameters

Request example

Responses

200 response

400 response

401 response

403 response

404 response

429 response

Update page settings (not blocks)

Parameters

Request body application/json

Request example

Responses

200 response

400 response

401 response

403 response

404 response

409 response

422 response

429 response

Delete a page

Parameters

Request example

Responses

204 response

400 response

401 response

403 response

404 response

429 response

Replace the ordered block list (≤ 50)

Parameters

Request body application/json

Request example

Responses

200 response

400 response

401 response

403 response

404 response

422 response

429 response

Publish a page

Parameters

Request example

Responses

200 response

400 response

401 response

403 response

404 response

409 response

422 response