Skip to content
Picogrid Legion

Batch create entity relationships

Batch create entity relationships

Open in ChatGPT ↗Open in Claude ↗
POST
/v3/entities/{entityId}/relationships/batch
curl --request POST \
  --url https://api.hopper.west.prod.govcloud.legion.picogrid.com/v3/entities/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/relationships/batch \
  --header 'Content-Type: application/json' \
  --data '{ "relationships": [] }'

Creates multiple relationships sharing the same source entity in a single request. The exactly-one-primary invariant is enforced per item in order; later items in the same (source, type) group observe the state produced by earlier items. Any item that violates the invariant rolls back the entire batch. Items whose (source, target, type) already exists as an active relationship are idempotent re-sends: the stored properties are overwritten with the item’s properties, is_primary is ignored (use PUT on the relationship to change the primary), and the existing row is returned. This differs from the single-create endpoint, which rejects duplicates with 409.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
entityId
required
string format: uuid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
relationships
required
Array<object>
object
is_primary
required
boolean
properties
object
key
additional properties
any
target_entity_id
required
string format: uuid
type
required
string
Example
{
  "relationships": []
}

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json
Array<object>
object
created_at
required
string
deleted_at
string
id
required
string format: uuid
is_primary
required
boolean
properties
object
key
additional properties
any
source_entity_id
required
string format: uuid
target_entity_id
required
string format: uuid
type
required
string
updated_at
required
string
Example
[]

400

Section titled “400”

Bad Request

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 400,
  "details": [
    {
      "Field": "organization_id",
      "Issue": "must be a valid UUID format"
    }
  ],
  "message": "Request cannot be processed due to invalid input",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 401,
  "details": [
    {
      "Field": "authorization_header",
      "Issue": "Bearer token is expired or malformed"
    }
  ],
  "message": "Authentication credentials are missing or invalid",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

403

Section titled “403”

Forbidden

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 403,
  "details": [
    {
      "Field": "required_scope",
      "Issue": "requires 'orion:settings:write' scope, but token only has 'orion:settings:read'"
    }
  ],
  "message": "Access denied: insufficient permissions for this resource",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

404

Section titled “404”

Not Found

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 404,
  "details": [
    {
      "Field": "organization_id",
      "Issue": "organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found"
    }
  ],
  "message": "The requested resource could not be found",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

409

Section titled “409”

Conflict

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 409,
  "details": [
    {
      "field": "email",
      "issue": "must be a valid email address"
    }
  ],
  "message": "Request conflicts with current state of the resource",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

422

Section titled “422”

Unprocessable Entity

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 422,
  "details": [
    {
      "field": "email",
      "issue": "must be a valid email address"
    }
  ],
  "message": "Request data is well-formed but violates business rules",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

500

Section titled “500”

Internal Server Error

Media typeapplication/json
object
category
required

The category of the error

string
code
required

The HTTP status code

number
details

Additional details about the error

Array<object>
object
field

The field that caused the error

string
issue

The specific issue with the field

string
message
required

A human-readable error message

string
status
required

The status of the response, always ‘error’ for error responses

string
timestamp
required

The timestamp when the error occurred

string format: date-time
trace_id
required

A unique identifier for tracing the error

string format: uuid
Example
{
  "category": "server_error",
  "code": 500,
  "details": [
    {
      "field": "field_name",
      "issue": "Field validation issue"
    }
  ],
  "message": "Internal Server Error",
  "status": "error",
  "timestamp": "2024-03-15T10:30:00Z",
  "trace_id": "b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f"
}

Version 3.14.0 · commit 0771262