Assets

Assets endpoints of the URLCrop API: 3 operations. Uploaded images (QR logos, OG images, page images).

Upload an image (≤ 2 MB)

POST/assets

Scope links:write
Scope qr:write
Scope pages:write
any one of these scopes

Any *:write scope; verified email. The type is detected from the file's magic bytes: PNG, JPEG or WebP only (no SVG, 415 unsupported_media_type). ≤ 2 MB (413), ≤ 4096 × 4096 px and ≤ 25 megapixels, or ≤ 16 megapixels for purpose: qr_logo (422 validation_failed). Re-encoded to PNG with metadata stripped. 60 uploads per hour per workspace (429, param: endpoint). One image is decoded at a time per API process: an upload that arrives while another is decoding answers 429 rate_limited, param: burst, Retry-After: 2.

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`.

Request body multipart/form-data

Field	Type	Description
filerequired	string	Format: binary
purposerequired	string	One of: `qr_logo`, `og_image`, `page_image`, `avatar`

Request body: Request bodyJSON

{
  "file": "string",
  "purpose": "qr_logo"
}

Example generated from the schema.

Request example

POST /assetscURL

curl -X POST 'https://api.urlcrop.com/v1/assets' \
  -H 'Authorization: Bearer uc_live_…' \
  -H 'Content-Type: multipart/form-data' \
  -d '{
  "file": "string",
  "purpose": "qr_logo"
}'

Responses

201 response

Uploaded

Asset schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `asset`
workspace_id	string
is_test	boolean
purposerequired	string	One of: `qr_logo`, `og_image`, `page_image`, `avatar`
urlrequired	string	15-minute signed `/v1/files/…` URL for previews. Logos are embedded server-side into QR renders; do not hot-link this URL.Format: uri
content_typerequired	string
width	integer \| null
height	integer \| null
bytesrequired	integer
moderation_staterequired	string	Image check state. `pending` covers not yet scanned; `review` and `blocked` hold the image back from pages, workspace icons and QR logos. Publishing or assigning an unchecked image answers `409 state_conflict` with `details[].code` `image_scan_pending` or `image_under_review`; a blocked one answers `422 validation_failed` with `image_not_allowed`.One of: `pending`, `safe`, `review`, `blocked`, `cleared`, `error`
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

201 response: 201 responseJSON

{
  "id": "ast_01JB4PA1B2C3D4E5F6G7H8J9K0",
  "object": "asset",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "purpose": "qr_logo",
  "url": "https://example.com",
  "content_type": "string",
  "width": 0,
  "height": 0,
  "bytes": 0,
  "moderation_state": "pending",
  "created_at": "2026-12-05T10:15:30.000Z"
}

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

413 response

File too large

Error codes: invalid_json

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).

413 response: 413 responseJSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_json",
    "message": "string",
    "param": "string",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://example.com",
    "details": [
      {
        "path": "string",
        "code": "string",
        "message": "string",
        "limit": 0,
        "used": 0,
        "resets_at": "2026-12-05T10:15:30.000Z",
        "upgrade_to": "string"
      }
    ]
  }
}

Example generated from the schema.

415 response

Unsupported media type

Error codes: invalid_json

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).

415 response: 415 responseJSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_json",
    "message": "string",
    "param": "string",
    "request_id": "req_01JB4N8ZK3Q9WXYZ0123456789",
    "doc_url": "https://example.com",
    "details": [
      {
        "path": "string",
        "code": "string",
        "message": "string",
        "limit": 0,
        "used": 0,
        "resets_at": "2026-12-05T10:15:30.000Z",
        "upgrade_to": "string"
      }
    ]
  }
}

Example generated from the schema.

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

Retrieve an asset (poll `moderation_state` after upload)

GET/assets/{id}

Scope links:read
Scope qr:read
Scope pages:read
any one of these scopes

The live asset of the workspace, with a fresh 15-minute signed url. After POST /assets the dashboard polls this until moderation_state leaves pending. Another workspace's asset or a deleted one 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

GET /assets/{id}cURL

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

Responses

200 response

Asset

Asset schema and example

Field	Type	Description
idrequired	string
objectrequired	string	Value: `asset`
workspace_id	string
is_test	boolean
purposerequired	string	One of: `qr_logo`, `og_image`, `page_image`, `avatar`
urlrequired	string	15-minute signed `/v1/files/…` URL for previews. Logos are embedded server-side into QR renders; do not hot-link this URL.Format: uri
content_typerequired	string
width	integer \| null
height	integer \| null
bytesrequired	integer
moderation_staterequired	string	Image check state. `pending` covers not yet scanned; `review` and `blocked` hold the image back from pages, workspace icons and QR logos. Publishing or assigning an unchecked image answers `409 state_conflict` with `details[].code` `image_scan_pending` or `image_under_review`; a blocked one answers `422 validation_failed` with `image_not_allowed`.One of: `pending`, `safe`, `review`, `blocked`, `cleared`, `error`
created_atrequired	string	ISO 8601 UTC with milliseconds.Format: date-time

200 response: 200 responseJSON

{
  "id": "ast_01JB4PA1B2C3D4E5F6G7H8J9K0",
  "object": "asset",
  "workspace_id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "is_test": false,
  "purpose": "qr_logo",
  "url": "https://example.com",
  "content_type": "string",
  "width": 0,
  "height": 0,
  "bytes": 0,
  "moderation_state": "pending",
  "created_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"
  }
}

Delete an asset

DELETE/assets/{id}

Scope links:write
Scope qr:write
Scope pages:write
any one of these scopes

Soft delete. 409 resource_in_use while a live QR code uses it; the asset is locked before the in-use check, so a delete racing an uncommitted QR write waits for it and then answers 409. Signed file URLs of a deleted asset answer 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 /assets/{id}cURL

curl -X DELETE 'https://api.urlcrop.com/v1/assets/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"
  }
}

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

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

Assets

Upload an image (≤ 2 MB)

Parameters

Request body multipart/form-data

Request example

Responses

201 response

400 response

401 response

403 response

404 response

413 response

415 response

422 response

429 response

Retrieve an asset (poll `moderation_state` after upload)

Parameters

Request example

Responses

200 response

400 response

401 response

403 response

404 response

429 response

Delete an asset

Parameters

Request example

Responses

204 response

400 response

401 response

403 response

404 response

409 response

429 response