> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aventure.vc/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aventure.vc/_mcp/server.

# Create relationship row

POST https://api.aventure.vc/v1/entities/{entityId}/relationships
Content-Type: application/json

Creates one relationship row from the full body payload and returns the row, including isCurrent/isPrimary. Omitted isCurrent and isPrimary default to true, so the row appears in default relationship reads. Pass either flag as false only to create a hidden curation row. Use entities relationships join for simple two-entity links and auto-orientation. For acceleratorParticipant row writes, sourceEntityId must be the participant entity, targetEntityId must be the accelerator entity with typeRecord=Investment Firm, and detail must be `batch=<label>` (or `program=<name>; batch=<label>` only for a distinct sub-program; program=/batch= must not repeat the accelerator name) plus asOf. Use entities relationships types for sourceRole and targetRole guidance. For affinity row writes, sourceEntityId is the member organization and targetEntityId is the provider organization.

Reference: https://docs.aventure.vc/api-reference/a-venture-api/entity-relationships/create-entity-relationship

## Authentication

- `Authorization` header (bearer token, required) — User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key
- `X-API-Key` header (required) — Admin API key for system-to-system write operations

## Request

### Path parameters

- `entityId` (string, required) — Canonical entity UUID

### Query parameters

- `sourceType` (enum, required) — Write provenance source type.
  - Allowed values: `requestChangeForm`, `newsArticle`, `blogArticle`, `firstPartyWebsite`, `relatedPartyWebsite`, `thirdPartyWebsite`, `llm`, `aventureStaff`
- `sourceDetail` (string, required) — Source detail or reviewer reference for the write.
- `sourceProvider` (string, optional) — Provider name for provider-native IDs or slugs.
- `sourceProviderId` (string, optional) — Provider-native source ID.
- `sourceProviderSlug` (string, optional) — Provider-native source slug.
- `actorType` (enum, optional) — Actor type; inferred as agent when agentChassis and agentModel are supplied, or as employee from an authenticated user JWT session.
  - Allowed values: `agent`, `employee`
- `agentChassis` (string, optional) — Agent chassis token for agent-authored writes.
- `agentModel` (string, optional) — Agent model id for agent-authored writes.

### Body (application/json)

- `relationshipType` (string, required) — General relationship type. Writable values: acceleratorParticipant, affinity, competingProductService, competitor, customer, fundManagerFirm, parent, productService, serviceProvider, similarCompany, spinOffFrom, successor. Use entities relationships types for policy flags; non-acquisition writes accept joinable=true values, while acquisition events must use the entity acquisitions endpoint with acquirerEntityId.
- `sourceEntityId` (string, required) — Source entity UUID. Non-acquisition PATCH/PUT writes may repoint this field in place. For type-oriented row writes this is the canonical source role: productService provider, fundManagerFirm fund, or acceleratorParticipant participant. For affinity this is the member organization. Move Product/Service provider ownership by repointing the productService row to the replacement provider; do not clear the current row.
- `targetEntityId` (string, required) — Target entity UUID. Non-acquisition PATCH/PUT writes may repoint this field in place. For acceleratorParticipant this is the accelerator entity and must have typeRecord=Investment Firm. For affinity this is the provider organization.
- `asOf` (date, optional, nullable) — Effective date for this relationship when known
- `detail` (string, optional, nullable) — Relationship-specific detail. Required for acceleratorParticipant as `batch=<label>`, or `program=<name>; batch=<label>` only when the program is a distinct sub-program (e.g. a Techstars track). The row already points to the accelerator entity, so program= must not repeat the accelerator name or the batch, and batch= must not contain the accelerator name; otherwise the write is rejected accelerator-detail-restates-target.
- `isCurrent` (boolean, optional, nullable) — Current-state curation flag. CREATE and PUT default omitted values to true; PATCH preserves the existing value when omitted; false hides the row from default reads.
- `isPrimary` (boolean, optional, nullable) — Primary/renderable curation flag. CREATE and PUT default omitted values to true; PATCH preserves the existing value when omitted; false hides the row from default reads.
- `source` (string, optional, nullable) — Source URL or compact source label copied to the relationship row

## Response

### 201

Created

- `entity` (object, required) — 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.
  - `id` (string, required) — Unique entity identifier
  - `image` (object, required) — Logo and monogram image metadata
    - `isMonogram` (boolean, required) — Whether entity image monogram
    - `logo` (string, optional, nullable)
    - `logoSquare` (string, optional, nullable)
  - `nameAlias` (list of object, required) — All names this entity has been known by — current alternates, DBAs, former names, and rebrand-source identities. Naming history (e.g. `Metaphor Systems` for the current `Exa` entity) lives here; never as a separate relationship type or `formerName` field.
    - `name` (string, required) — Alternate name text
    - `displayable` (boolean, optional, nullable) — Show this alias in public name displays.
    - `type` (enum, optional, nullable) — Alias type classification
      - Allowed values: `alternativeDba`, `relatedLegal`
  - `nameBrand` (string, required) — Resolved display brand name
  - `slug` (string, required) — URL-safe identifier
  - `createdAt` (datetime, optional, nullable) — Record creation timestamp
  - `defaultCurrency` (string, optional, nullable) — Default currency code (ISO 4217)
  - `foundedYear` (integer, optional, nullable) — Year the entity was founded
  - `lastModifiedAt` (datetime, optional, nullable) — Provenance-grounded last-modified watermark (schema.org dateModified). Advances only when a real, consumer-meaningful data point changes via a recorded provenance event — never on timestamp-only writes, migrations, or index refreshes. Pairs with createdAt (dateCreated) and grounds the sitemap lastmod.
  - `nameLegal` (string, optional, nullable) — Registered legal name
  - `operatingStatus` (string, optional, nullable) — Current operating status. Use Acquired Subsidiary when the entity was acquired and still operates; use Acquired only when it is terminal, folded, or closed.
  - `publicId` (string, optional, nullable) — Stable, immutable public handle (e.g. `eV1StGXR8Z5a`). Never changes once assigned, unlike the slug. Null on projections that do not select it and on rows still awaiting handle backfill.
  - `publicUrl` (string, optional, nullable) — Absolute public profile URL on the aVenture front-end, e.g. `https://aventure.vc/non-profits/{slug}`, derived from the typeRecord's canonical route family. Null when the route needs relationship context or the record has no direct public SSR route (Business Line, Organization, Product, Service, or a non-public slug). EntityDetail.publicUrl resolves Business Line parent context. Product/Service pages are provider-nested: compose the provider entity's publicUrl + `/products-services/` + this record's slug, or consume the sitemap-urls slot paths, which already emit the composed child routes.
  - `sitemap` (object, optional, nullable) — Sub-route eligibility, populated by the sitemap projection. Null on non-sitemap reads to keep thin payloads compact.
    - `hasAnalysis` (boolean, required) — Whether the profile Analysis sub-route should be emitted.
    - `hasEmployees` (boolean, required) — Whether the profile Employees sub-route should be emitted.
    - `hasFundraising` (boolean, required) — Whether the profile Fundraising sub-route should be emitted.
    - `hasNews` (boolean, required) — Whether the profile News sub-route should be emitted.
    - `productServiceSlug` (list of string, required) — Slugs of related Product/Service entities that should each get their own `/companies/<slug>/products-services/<productSlug>` URL, capped at `MAX_PRODUCT_SERVICE_SLUGS` server-side. Derived from current `productService` relationships in either stored direction; the entity relationships resource is the authoritative, read-your-writes view of those joins.
    - `hasAcquisitions` (boolean, optional, default: false) — Whether `/companies/<slug>/acquisitions` should be emitted. True only when an acquisition relationship exists AND both the acquired and acquirer entities are publicly visible. A confirmed acquisition relationship row with this flag `false` (or with `entities acquisitions list` returning zero rows) means a counterpart entity is still hidden -- publish it -- it is a visibility gate, not list lag.
  - `typeRecord` (enum, optional, nullable) — Entity type classification
    - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
  - `updatedAt` (datetime, optional, nullable) — Last modification timestamp
- `relationship` (list of object, required) — Nested relationships for the joined entity
- `relationshipType` (string, required) — 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.
- `asOf` (date, optional, nullable) — Effective date for this relationship when known
- `comparisonSignals` (object, optional, nullable) — 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.
  - `ownership` (list of string, required) — Provider ownership structure (current typeOwnership tags)
  - `pricingModel` (list of string, required) — Provider pricing/revenue model (current typeRevenue tags)
  - `sellsTo` (list of string, required) — Customer types the provider sells to (current typeCustomer tags)
  - `fundingStage` (enum, optional, nullable) — Latest funding stage when known
    - Allowed values: `Angel`, `Pre-Seed`, `Seed`, `Series A`, `Series B`, `Series C`, `Series D`, `Series E`, `Series F`, `Series G`, `Series H`, `Series I`, `Series J`, `Series K`, `Series L`, `Series M`, `Series N`, `Series O`, `Series P`, `Series Q`, `Series R`, `Series S`, `Series T`, `Series U`, `Series V`, `Series W`, `Series X`, `Series Y`, `Series Z`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Public`, `Acquired`, `Acquired Subsidiary`
  - `totalRaised` (double, optional, nullable) — Total capital raised when known
  - `website` (string, optional, nullable) — Provider website URL when known
- `createdAt` (datetime, optional, nullable)
- `detail` (string, optional, nullable) — 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.
- `id` (integer, optional, nullable) — Integer entity_relationship.id row id, not an entity UUID
- `isCurrent` (boolean, optional, nullable) — Current-state curation flag for this relationship row. Default relationship reads return only rows where isCurrent=true and isPrimary=true.
- `isPrimary` (boolean, optional, nullable) — Primary/renderable curation flag for this relationship row. isCurrent=false or isPrimary=false hides the row from default relationship reads.
- `source` (string, optional, nullable) — Source URL or compact source label copied to the relationship row
- `sourceEntityId` (string, optional, nullable) — 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.
- `targetEntityId` (string, optional, nullable) — 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.
- `updatedAt` (datetime, optional, nullable)

## Examples

**Request**

```json
{
  "relationshipType": "string",
  "sourceEntityId": "string",
  "targetEntityId": "string"
}
```

**Response**

```json
{
  "entity": {
    "id": "string",
    "image": {
      "isMonogram": true,
      "logo": "string",
      "logoSquare": "string"
    },
    "nameAlias": [
      {
        "name": "Bun",
        "displayable": true,
        "type": "alternativeDba"
      }
    ],
    "nameBrand": "string",
    "slug": "aventure-vc",
    "createdAt": "2024-01-15T09:30:00Z",
    "defaultCurrency": "string",
    "foundedYear": 1,
    "lastModifiedAt": "2024-01-15T09:30:00Z",
    "nameLegal": "string",
    "operatingStatus": "string",
    "publicId": "eV1StGXR8Z5a",
    "publicUrl": "string",
    "sitemap": {
      "hasAnalysis": true,
      "hasEmployees": true,
      "hasFundraising": true,
      "hasNews": true,
      "productServiceSlug": [
        "string"
      ],
      "hasAcquisitions": false
    },
    "typeRecord": "Company",
    "updatedAt": "2024-01-15T09:30:00Z"
  },
  "relationship": [
    {
      "entity": {
        "id": "string",
        "image": {
          "isMonogram": true,
          "logo": "string",
          "logoSquare": "string"
        },
        "nameAlias": [
          {
            "name": "Bun",
            "displayable": true,
            "type": "alternativeDba"
          }
        ],
        "nameBrand": "string",
        "slug": "aventure-vc",
        "createdAt": "2024-01-15T09:30:00Z",
        "defaultCurrency": "string",
        "foundedYear": 1,
        "lastModifiedAt": "2024-01-15T09:30:00Z",
        "nameLegal": "string",
        "operatingStatus": "string",
        "publicId": "eV1StGXR8Z5a",
        "publicUrl": "string",
        "sitemap": {
          "hasAnalysis": true,
          "hasEmployees": true,
          "hasFundraising": true,
          "hasNews": true,
          "productServiceSlug": [
            "string"
          ],
          "hasAcquisitions": false
        },
        "typeRecord": "Company",
        "updatedAt": "2024-01-15T09:30:00Z"
      },
      "relationship": [
        null
      ],
      "relationshipType": "string",
      "asOf": "2023-01-15",
      "comparisonSignals": {
        "ownership": [
          "string"
        ],
        "pricingModel": [
          "string"
        ],
        "sellsTo": [
          "string"
        ],
        "fundingStage": "Angel",
        "totalRaised": 1.1,
        "website": "string"
      },
      "createdAt": "2024-01-15T09:30:00Z",
      "detail": "string",
      "id": 1,
      "isCurrent": true,
      "isPrimary": true,
      "source": "string",
      "sourceEntityId": "string",
      "targetEntityId": "string",
      "updatedAt": "2024-01-15T09:30:00Z"
    }
  ],
  "relationshipType": "string",
  "asOf": "2023-01-15",
  "comparisonSignals": {
    "ownership": [
      "string"
    ],
    "pricingModel": [
      "string"
    ],
    "sellsTo": [
      "string"
    ],
    "fundingStage": "Angel",
    "totalRaised": 1.1,
    "website": "string"
  },
  "createdAt": "2024-01-15T09:30:00Z",
  "detail": "string",
  "id": 1,
  "isCurrent": true,
  "isPrimary": true,
  "source": "string",
  "sourceEntityId": "string",
  "targetEntityId": "string",
  "updatedAt": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python
import requests

url = "https://api.aventure.vc/v1/entities/entityId/relationships"

querystring = {"actorType":"agent","agentChassis":"codex-cli","sourceDetail":"aventure.vc","sourceProvider":"TechCrunch","sourceProviderId":"tc-2026-05-20-example-round","sourceProviderSlug":"example-round","sourceType":"requestChangeForm"}

payload = {
    "relationshipType": "string",
    "sourceEntityId": "string",
    "targetEntityId": "string"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.aventure.vc/v1/entities/entityId/relationships?actorType=agent&agentChassis=codex-cli&sourceDetail=aventure.vc&sourceProvider=TechCrunch&sourceProviderId=tc-2026-05-20-example-round&sourceProviderSlug=example-round&sourceType=requestChangeForm';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"relationshipType":"string","sourceEntityId":"string","targetEntityId":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aventure.vc/v1/entities/entityId/relationships?actorType=agent&agentChassis=codex-cli&sourceDetail=aventure.vc&sourceProvider=TechCrunch&sourceProviderId=tc-2026-05-20-example-round&sourceProviderSlug=example-round&sourceType=requestChangeForm"

	payload := strings.NewReader("{\n  \"relationshipType\": \"string\",\n  \"sourceEntityId\": \"string\",\n  \"targetEntityId\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.aventure.vc/v1/entities/entityId/relationships?actorType=agent&agentChassis=codex-cli&sourceDetail=aventure.vc&sourceProvider=TechCrunch&sourceProviderId=tc-2026-05-20-example-round&sourceProviderSlug=example-round&sourceType=requestChangeForm")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"relationshipType\": \"string\",\n  \"sourceEntityId\": \"string\",\n  \"targetEntityId\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.aventure.vc/v1/entities/entityId/relationships?actorType=agent&agentChassis=codex-cli&sourceDetail=aventure.vc&sourceProvider=TechCrunch&sourceProviderId=tc-2026-05-20-example-round&sourceProviderSlug=example-round&sourceType=requestChangeForm")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"relationshipType\": \"string\",\n  \"sourceEntityId\": \"string\",\n  \"targetEntityId\": \"string\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.aventure.vc/v1/entities/entityId/relationships?actorType=agent&agentChassis=codex-cli&sourceDetail=aventure.vc&sourceProvider=TechCrunch&sourceProviderId=tc-2026-05-20-example-round&sourceProviderSlug=example-round&sourceType=requestChangeForm', [
  'body' => '{
  "relationshipType": "string",
  "sourceEntityId": "string",
  "targetEntityId": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.aventure.vc/v1/entities/entityId/relationships?actorType=agent&agentChassis=codex-cli&sourceDetail=aventure.vc&sourceProvider=TechCrunch&sourceProviderId=tc-2026-05-20-example-round&sourceProviderSlug=example-round&sourceType=requestChangeForm");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"relationshipType\": \"string\",\n  \"sourceEntityId\": \"string\",\n  \"targetEntityId\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "relationshipType": "string",
  "sourceEntityId": "string",
  "targetEntityId": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.aventure.vc/v1/entities/entityId/relationships?actorType=agent&agentChassis=codex-cli&sourceDetail=aventure.vc&sourceProvider=TechCrunch&sourceProviderId=tc-2026-05-20-example-round&sourceProviderSlug=example-round&sourceType=requestChangeForm")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```