Workspaces
Workspaces endpoints of the URLCrop API: 1 operation. The tenant. Every other resource belongs to exactly one workspace (live or test).
Get the current workspace
GET/workspace
- Scope workspace:read
The workspace the API key is bound to, or the one named by X-Workspace-Id for sessions.
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 example
GET /workspacecURL
curl 'https://api.urlcrop.com/v1/workspace' \
-H 'Authorization: Bearer uc_live_…'Responses
200 response
Workspace
Workspace schema and example
Field Type Description idrequired string objectrequired string Value: workspaceorganization_idrequired string namerequired string max length 80 slugrequired string avatar_url string | null Workspace icon as a 15-minute signed /v1/files/...URL (PNG), or null when none is set. Set it withWorkspaceUpdate.avatar_asset_key.Format: urishort_link_host string Host new short URLs show for the default domain. Equals settings.default_domain, except while staff run the backup short domain (ops switchshort_host_fallback) and the workspace prefers it (short_host_preference: alt), when it is the backup host (for examplego.crop.sh). Display only: stored links keep their domain, and both hosts redirect.short_host_alt string The backup short host, present only while it is on offer (ops switch short_host_fallbackon and the host configured). The dashboard shows the Short link domain choice only when this is present.short_host_preference string Which platform short host this workspace shows: alt(the backup host) orprimary. Takes effect only while staff run the backup short domain (ops switchshort_host_fallback) and it is configured; otherwiseshort_link_hostis the primary host.One of:alt,primaryuse_casesrequired array of string What the workspace is used for (onboarding step 2, editable in settings); empty until chosen. Set it with WorkspaceUpdate.use_cases.max items 6environmentrequired string One of: live,testis_testrequired boolean Mirrors environment == "test"; present on every resource.live_workspace_id string | null For a test workspace, its live twin. test_workspace_id string | null For a live workspace, its paired test workspace (null until test mode is enabled). parent_workspace_id string | null Agency client workspaces (Phase 4). planrequired string One of: free,starter,pro,business,agency,enterprisestatusrequired string One of: active,past_due,suspended,deletedsettingsrequired object settings. timezone string settings. append_click_id boolean Append ?ucid=<click_id>to destinations.settings. click_id_param string settings. default_domain string Hostname used when LinkCreate.domainis omitted.settings. approvals_enabled boolean Approval flows switched on (Agency+, approval_flows). Editor link writes then wait for an Owner or Admin (202with anApprovalRequest). Effective only while the plan includesapproval_flows.created_atrequired string ISO 8601 UTC with milliseconds.Format: date-time updated_atrequired string ISO 8601 UTC with milliseconds.Format: date-time deleted_at string | null Set while the workspace is soft-deleted ( status=deleted).Format: date-timerestorable_until string | null Last moment the Owner can restore a soft-deleted workspace ( deleted_at+ 30 days); null when active.Format: date-time200 response: liveJSON{ "id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K", "object": "workspace", "organization_id": "org_01JB4M0A1B2C3D4E5F6G7H8J9K", "name": "Brand India", "slug": "brand-india", "environment": "live", "is_test": false, "live_workspace_id": null, "test_workspace_id": "ws_01JB4M0B2C3D4E5F6G7H8J9K0L", "parent_workspace_id": null, "plan": "pro", "status": "active", "settings": { "timezone": "Asia/Kolkata", "append_click_id": true, "click_id_param": "ucid", "default_domain": "crop.sh" }, "avatar_url": null, "use_cases": [ "marketing_campaigns", "qr_print" ], "created_at": "2026-12-01T08:00:00.000Z", "updated_at": "2026-12-05T10:15:30.000Z" }400 response
Malformed request (
invalid_json,invalid_query,missing_header,invalid_cursor,invalid_sort,invalid_expand). Any credentialed operation can return it: a credential in the query string (api_key,access_token) isinvalid_query, and a session request withoutX-Workspace-Idon a workspace-scoped route ismissing_header.Error codes:
invalid_json,invalid_query,missing_header,invalid_cursor,invalid_sort,invalid_expandError 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_errorerror. coderequired string Complete error-code catalogue. @urlcrop/shared/errorsis tested against this list.paramon 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,timeouterror. 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].codegives the reason (missing_credentials,invalid_api_key,api_key_revoked,api_key_expired,session_expired,publishable_key_not_allowed).Error codes:
unauthenticatedError 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_errorerror. coderequired string Complete error-code catalogue. @urlcrop/shared/errorsis tested against this list.paramon 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,timeouterror. 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_reachedwithparamnaming the plan limit key). Any credentialed operation can return it: an API key on a session-only route isinsufficient_scope, a session write without an allowedOriginisorigin_not_allowed, and an API key whose plan has no API access isfeature_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_reachedError 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_errorerror. coderequired string Complete error-code catalogue. @urlcrop/shared/errorsis tested against this list.paramon 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,timeouterror. 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-Idnames a workspace the user is not an active member of.Error codes:
resource_not_foundError 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_errorerror. coderequired string Complete error-code catalogue. @urlcrop/shared/errorsis tested against this list.paramon 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,timeouterror. 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_limitedError 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_errorerror. coderequired string Complete error-code catalogue. @urlcrop/shared/errorsis tested against this list.paramon 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,timeouterror. 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" } }500 response
Unexpected server error (
internal_error,upstream_unavailable,service_unavailable,timeout).Error codes:
invalid_json,internal_error,upstream_unavailable,service_unavailable,timeoutError 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_errorerror. coderequired string Complete error-code catalogue. @urlcrop/shared/errorsis tested against this list.paramon 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,timeouterror. 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). 500 response: 500 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.