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

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
`uri`required	string	Entity website or URI
`ticker`optional	string	Entity symbol/ticker (e.g., 'HARB', 'NVDA'). Auto-generated from name if not provided.
`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

Example request

curl

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"
  ]
}'

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 (null for legacy callers)
`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