Join two entities

View as Markdown
Creates one directed relationship between two existing entities and returns the row. The created row is always isCurrent=true and isPrimary=true, so it appears in default relationship reads. relationshipType must be joinable=true from entities relationships types; its direction/sourceRole/targetRole fields describe whether source/target order is symmetric, auto-oriented, or directional. For parent, sourceEntityId is the parent and targetEntityId is the child. For affinity, sourceEntityId is the member organization and targetEntityId is the provider organization; the companies list affinity filter accepts provider names only. For productService, one side must be Product or Service and the provider side must be Company, Nonprofit, Government, or Business Line; Investment Firm, Fund, and group-only Organization are rejected because they cannot own products/services. AcquisitionManaged and readOnly types are rejected. For acceleratorParticipant, one side must be the participant entity and the other side must be the accelerator entity with typeRecord=Investment Firm; the join endpoint stores participant as source and accelerator as target. acceleratorParticipant requires detail as `batch=<label>` or `program=<name>; batch=<label>` plus asOf. Use entities relationships row create when writing historic/non-primary curation flags. Missing or malformed query parameters return 400. A relationshipType whose source/target entity-type pairing is not accepted, an acquisitionManaged or readOnly relationshipType, missing acceleratorParticipant detail/asOf, or sourceEntityId equal to targetEntityId returns 422. A productService join that would create an ambiguous Product/Service slug route, a duplicate relationship, or parent/acquisition exclusivity for the same unordered entity pair returns 409; duplicate directional conflicts name the existing row and the required sourceRole/targetRole orientation. An unresolved sourceEntityId or targetEntityId returns 404.

Authentication

AuthorizationBearer

User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key

OR
X-API-Keystring

Admin API key for system-to-system write operations

Query parameters

sourceEntityIdstringRequiredformat: "uuid"

Relationship source entity UUID, not provenance source metadata. For parent this is the parent entity. For affinity this is the member organization. For acceleratorParticipant this may be either side; join auto-orients so the stored source is the participant entity.

targetEntityIdstringRequiredformat: "uuid"

Relationship target entity UUID. For parent this is the child entity. For affinity this is the provider organization. For acceleratorParticipant this may be either side, but exactly one side must be the accelerator entity with typeRecord=Investment Firm.

relationshipTypestringRequired
Joinable EntityRelationshipType, one of: acceleratorParticipant, affinity, competingProductService, competitor, customer, fundManagerFirm, parent, productService, serviceProvider, similarCompany, spinOffFrom, successor. Use entities relationships types; valid join values have joinable=true and expose direction/sourceRole/targetRole labels.
asOfdateOptional
Effective date for this relationship when known
sourcestringOptional
Source URL or compact source label copied to the relationship row
detailstringOptional

Relationship-specific detail. Required for acceleratorParticipant as batch=<label> or program=<name>; batch=<label>. Pair it with asOf.

sourceTypeenumRequired
Write provenance source type.
sourceDetailstringRequired
Source detail or reviewer reference for the write.
sourceProviderstringOptional

Provider name for provider-native IDs or slugs.

sourceProviderIdstringOptional

Provider-native source ID.

sourceProviderSlugstringOptional

Provider-native source slug.

actorTypeenumOptional

Actor type; inferred as agent when agentChassis and agentModel are supplied, or as employee from an authenticated user JWT session.

Allowed values:
agentChassisstringOptional

Agent chassis token for agent-authored writes.

agentModelstringOptional

Agent model id for agent-authored writes.

Response

Created relationship row. Directional warnings also appear in Warning, X-Contract-Warning-Code, and X-Contract-Warning-Key headers.

entityobject

Joined entity on the other side of this relationship — read-only display projection. Writes identify both sides only via the flat sourceEntityId and targetEntityId UUIDs, never a nested entity object.

relationshiplist of objects
Nested relationships for the joined entity
relationshipTypestring

Canonical relationship type, one of: acceleratorParticipant, acquirer, affinity, calculated, competingProductService, competitor, customer, fundManagerFirm, parent, productService, serviceProvider, similarCompany, spinOffFrom, successor. Similarity endpoint rows use stored relationship types when a curation row exists and calculated when the row comes from semantic/vector similarity.

asOfdate or nullOptional
Effective date for this relationship when known
comparisonSignalsobject or nullOptional

Competitive comparison signals for the joined entity when it is a product/service provider — sells-to, pricing model, ownership, funding, and website. Null for every other joined entity. Lets comparison surfaces render provider columns without a second per-provider fetch.

createdAtdatetime or nullOptional
detailstring or nullOptional

Relationship-specific detail. acceleratorParticipant rows use batch=<label>, or program=<name>; batch=<label> only for a distinct sub-program. program= never repeats the accelerator name or the batch, and batch= never contains the accelerator name — the row already points to the accelerator entity.

idinteger or nullOptional

Integer entity_relationship.id row id, not an entity UUID

isCurrentboolean or nullOptional

Current-state curation flag for this relationship row. Default relationship reads return only rows where isCurrent=true and isPrimary=true.

isPrimaryboolean or nullOptional

Primary/renderable curation flag for this relationship row. isCurrent=false or isPrimary=false hides the row from default relationship reads.

sourcestring or nullOptional
Source URL or compact source label copied to the relationship row
sourceEntityIdstring or nullOptionalformat: "uuid"

Canonical source entity UUID stored on the relationship row. Compare with the requested entity id and /v1/entities/relationships/types sourceRole/targetRole to orient directional relationships such as parent.

targetEntityIdstring or nullOptionalformat: "uuid"

Canonical target entity UUID stored on the relationship row. Compare with the requested entity id and /v1/entities/relationships/types sourceRole/targetRole to orient directional relationships such as parent.

updatedAtdatetime or nullOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
406
Not Acceptable Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error