Create one entity URL
Create one entity-owned URL row. Defaults to current and primary; terminal Acquired, Closed, or Inactive entities reject current website rows.
Authentication
User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key
Admin API key for system-to-system write operations
Path parameters
Query parameters
Provider name for provider-native IDs or slugs.
Provider-native source ID.
Provider-native source slug.
Actor type; inferred as agent when agentChassis and agentModel are supplied, or as employee from an authenticated user JWT session.
Agent chassis token for agent-authored writes.
Agent model id for agent-authored writes.
Request
Whether the owner currently uses this URL. Defaults true on create; update omits preserve the existing value. For terminal entity operatingStatus values (Acquired, Closed, Inactive), website rows must be written with isCurrent=false.
Whether this is the owner’s primary URL for its urlType. Defaults true for current create rows; update omits preserve the existing value. Setting isCurrent=false forces isPrimary=false; terminal entities cannot have a current primary website row. Website primacy belongs to the homepage: while the owner has a current root-URL website row, a deep-path or query-carrying website URL cannot be primary — such a create is stored with isPrimary=false (even when requested true), and an update promoting one, or moving a primary row’s URL across the root/deep boundary, is rejected (409).
Crawl/check status label, not lifecycle.
Last crawl/check timestamp.
Absolute owner URL (https://…), normalized before validation. Must be a page the owner actually operates. URL surface misclassification is rejected (422): news/press articles such as a dated article path or a techcrunch.com/businesswire.com/forbes.com article — record it through the owner’s canonical news create surface, NEVER as a website link; domain-marketplace/for-sale pages (dan.com, hugedomains.com, …); and binary assets (.png/.pdf/…). Eponymous Product/Service full-create may omit the entire URL link array when no distinct official page URL exists. Submit either www. or apex host form; after write the stored host form is normalized from live evidence — apex (no www.) when that route serves healthy without redirecting to www., the www. form otherwise — so the persisted URL may differ from the submitted one by its www. label.
Canonical platform role for the URL, from EntityUrlType (website, linkedin, twitter, github, crunchbase, wikipedia, appstore, …). Pick the platform the URL host belongs to for owner-specific platform paths. Platform host roots and first-party product pages stay website; security quote paths, social profiles, marketplace listings, and similar owner-specific platform paths use their platform type. Lifecycle (former domain, rebrand source) lives on isCurrent/isPrimary, never here. Required on create unless inferable from the URL host/path.
Response
Canonical absolute HTTP URL value - validates scheme + host at construction
true = owner currently uses this URL; false = historical/former (rebrand source domain, deprecated platform handle). The lifecycle state lives here, NEVER in the urlType discriminator.
true = canonical/primary URL of this urlType for this owner. Only one row per (owner, urlType) may be isCurrent=true AND isPrimary=true.
Owning record, nested ids only: owner.entityId or owner.personId — exactly one is set, and no name fields. Writes are scoped by the owning entity/person route; owner is never a write field.