Create New Graph Database

post/v1/graphs

Part of Graphs.

Creates a graph asynchronously. Returns an OperationEnvelope with operation_id for SSE progress at /v1/operations/{operation_id}/stream. Entity graphs require initial_entity. Supports Idempotency-Key header.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field Type Description

metadatarequired

GraphMetadata

Graph metadata including name, description, and schema extensions

GraphMetadata fields

Field	Type	Description
`graph_name`required	string	Display name for the graph
`description`optional	string	Optional description
`schema_extensions`optional	string[]	Schema extensions to enable
`tags`optional	string[]	Tags for organizing graphs

instance_tieroptional

string

Instance tier: ladybug-standard, ladybug-large, ladybug-xlarge

Default: ladybug-standard

Constraints: matches ^(ladybug-standard|ladybug-large|ladybug-xlarge)$

custom_schemaoptional

CustomSchemaDefinition

Custom schema definition to apply. If provided, creates a generic custom graph. If omitted, creates an entity graph using schema_extensions.

CustomSchemaDefinition fields

Field	Type	Description
`name`required	string	Schema name
`version`optional	string	Schema version Default: `1.0.0`
`description`optional	string	Schema description
`extends`optional	string	Base schema to extend (e.g., 'base' for common utilities)
`nodes`optional	object[]	List of node definitions with properties
`relationships`optional	object[]	List of relationship definitions
`metadata`optional	object	Additional schema metadata

initial_entityoptional

InitialEntityData

Initial entity for the graph. Required for entity graphs (when custom_schema is omitted). Omit only when providing custom_schema for a generic graph.

InitialEntityData fields

Field	Type	Description
`name`required	string	Entity name Constraints: 1–255 characters
`uri`required	string	Entity website or URI Constraints: at least 1 character
`ticker`optional	string	Entity symbol/ticker (e.g., 'HARB', 'NVDA'). Auto-generated from name if not provided. Constraints: 1–10 characters
`cik`optional	string	CIK number for SEC filings
`sic`optional	string	SIC code
`sic_description`optional	string	SIC description
`category`optional	string	Business category
`state_of_incorporation`optional	string	State of incorporation
`fiscal_year_end`optional	string	Fiscal year end (MMDD)
`ein`optional	string	Employer Identification Number
`entity_type`optional	string	Entity legal form (e.g. 'corporation', 'llc' / 'limited_liability_company', 'partnership', 'sole_proprietorship', 'non_profit'). Drives the graph's default Reporting Style at creation — partnership and llc get dedicated equity-form Styles; everything else defaults to corporate. Blank falls back to corporate.
`reporting_style_id`optional	string	Optional explicit Reporting Style Structure id to pin on the entity, overriding the entity_type-derived default. Leave blank to derive from entity_type. Change later via the change-reporting-style operation.

create_entityoptional

boolean

Whether to create the entity node and upload initial data. Only applies when initial_entity is provided. Set to False to create graph without populating entity data (useful for file-based ingestion workflows).

Default: true

tagsoptional

string[]

Optional tags for organization

Constraints: at most 10 items

Example request

curl · example 1 of 4

curl -X POST "https://api.robosystems.ai/v1/graphs" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "create_entity": true,
  "initial_entity": {
    "cik": "0001234567",
    "ein": "12-3456789",
    "name": "Acme Consulting LLC",
    "state_of_incorporation": "Delaware",
    "uri": "https://acmeconsulting.com"
  },
  "instance_tier": "ladybug-standard",
  "metadata": {
    "description": "Professional consulting services with full accounting integration",
    "graph_name": "Acme Consulting LLC",
    "schema_extensions": [
      "roboledger"
    ]
  },
  "tags": [
    "consulting",
    "professional-services",
    "production"
  ]
}'

curl · example 2 of 4

curl -X POST "https://api.robosystems.ai/v1/graphs" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_schema": {
    "description": "People, companies, and projects schema",
    "extends": "base",
    "metadata": {
      "domain": "custom_graph_demo"
    },
    "name": "custom_graph_demo",
    "nodes": [
      {
        "name": "Person",
        "properties": [
          {
            "name": "identifier",
            "type": "STRING",
            "is_primary_key": true
          },
          {
            "name": "name",
            "type": "STRING",
            "nullable": false
          },
          {
            "name": "title",
            "type": "STRING"
          }
        ]
      },
      {
        "name": "Company",
        "properties": [
          {
            "name": "identifier",
            "type": "STRING",
            "is_primary_key": true
          },
          {
            "name": "name",
            "type": "STRING",
            "nullable": false
          },
          {
            "name": "industry",
            "type": "STRING"
          }
        ]
      }
    ],
    "relationships": [
      {
        "from_node": "Person",
        "name": "PERSON_WORKS_FOR_COMPANY",
        "properties": [
          {
            "name": "role",
            "type": "STRING"
          }
        ],
        "to_node": "Company"
      }
    ],
    "version": "1.0.0"
  },
  "instance_tier": "ladybug-standard",
  "metadata": {
    "description": "Custom graph demo with people, companies, and projects",
    "graph_name": "custom_graph_demo_1234",
    "schema_extensions": []
  },
  "tags": [
    "custom",
    "demo",
    "generic"
  ]
}'

curl · example 3 of 4

curl -X POST "https://api.robosystems.ai/v1/graphs" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_schema": {
    "description": "Inventory tracking with products and warehouses",
    "metadata": {
      "industry": "retail"
    },
    "name": "inventory_management",
    "nodes": [
      {
        "name": "Product",
        "properties": [
          {
            "name": "sku",
            "type": "STRING",
            "is_primary_key": true
          },
          {
            "name": "name",
            "type": "STRING",
            "nullable": false
          },
          {
            "name": "price",
            "type": "DOUBLE"
          },
          {
            "name": "quantity",
            "type": "INT64"
          }
        ]
      },
      {
        "name": "Warehouse",
        "properties": [
          {
            "name": "identifier",
            "type": "STRING",
            "is_primary_key": true
          },
          {
            "name": "location",
            "type": "STRING",
            "nullable": false
          }
        ]
      }
    ],
    "relationships": [
      {
        "from_node": "Product",
        "name": "STORED_IN",
        "properties": [
          {
            "name": "quantity",
            "type": "INT64"
          }
        ],
        "to_node": "Warehouse"
      }
    ],
    "version": "1.0.0"
  },
  "instance_tier": "ladybug-standard",
  "metadata": {
    "description": "Inventory management system",
    "graph_name": "warehouse_inventory",
    "schema_extensions": []
  },
  "tags": [
    "inventory",
    "retail"
  ]
}'

curl · example 4 of 4

curl -X POST "https://api.robosystems.ai/v1/graphs" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_schema": {
    "name": "customer_analytics",
    "nodes": [],
    "relationships": [],
    "version": "1.0.0"
  },
  "instance_tier": "ladybug-standard",
  "metadata": {
    "description": "Graph database for customer relationship and behavior analysis",
    "graph_name": "Customer Analytics Graph",
    "schema_extensions": []
  },
  "tags": [
    "analytics",
    "customers",
    "marketing"
  ]
}'

Responses

202 Successful Response

Field	Type	Description
`operation`required	string	Kebab-case operation name
`operationId`required	string	op_-prefixed ULID for audit and SSE correlation
`status`required	string	Operation lifecycle state One of: `completed`, `pending`, `failed`
`result`optional	any	Command-specific result payload
`at`required	string	ISO-8601 UTC timestamp
`createdBy`optional	string	User ID that initiated the operation
`idempotentReplay`optional	boolean	True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions. Default: `false`

Status	Meaning
400	Invalid request
401	Authentication required
402	Payment required — add a payment method or check org graph limit
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error