Graph Operations

Create Subgraph

Set fork_parent=true to clone parent graph data into the new subgraph (async, returns a pending OperationEnvelope). Without fork_parent, creates an empty subgraph synchronously.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

post/v1/graphs/{graph_id}/operations/create-subgraph

Request

  • Base URL: https://api.robosystems.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.robosystems.ai/v1/graphs/{graph_id}/operations/create-subgraph
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

graph_idstring required

Headers

Idempotency-Keystring nullable

Request body

namestring required

Alphanumeric name for the subgraph (e.g., dev, staging, prod1)

display_namestring required

Human-readable display name for the subgraph

descriptionstring nullable

Optional description of the subgraph's purpose

schema_extensionsstring[]

Schema extensions to include (inherits from parent by default)

subgraph_type'static' | 'knowledge' | 'empty'

Types of subgraphs.

metadataobject nullable

Additional metadata for the subgraph

fork_parentboolean

If true, copy all data from parent graph to create a 'fork'

Example request

{
  "name": "dev",
  "display_name": "Development Environment",
  "description": "Development environment for testing new features",
  "schema_extensions": [
    "roboledger",
    "roboinvestor"
  ],
  "metadata": {
    "environment": "development",
    "team": "engineering"
  }
}

Response

Successful Response

operationstring required

Kebab-case operation name

operationIdstring required

op_-prefixed ULID for audit and SSE correlation

status'completed' | 'pending' | 'failed' required

Operation lifecycle state

resultunknown
atstring required

ISO-8601 UTC timestamp

createdBystring nullable

User ID that initiated the operation

idempotentReplayboolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Changes

No recorded changes to this operation across all 1 revision of this API.