Delete Subgraph

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

Set backup_first=true to create a safety backup before deletion. Requires admin role on the parent graph.

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.

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.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Header parameters

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

Request body

Required, application/json.

Field Type Description

Field	Type	Description
`subgraph_name`required	string	Subgraph name to delete (e.g., 'dev', 'staging')
`force`optional	boolean	Delete even if subgraph contains data Default: `false`
`backup_first`optional	boolean	Take a full backup of the subgraph before deleting it. The backup is registered on the parent graph's backup list, where it can be listed and downloaded after the subgraph is gone. If the backup fails the subgraph is not deleted. Default: `true`

subgraph_namerequired

string

Subgraph name to delete (e.g., 'dev', 'staging')

forceoptional

boolean

Delete even if subgraph contains data

Default: false

backup_firstoptional

boolean

Take a full backup of the subgraph before deleting it. The backup is registered on the parent graph's backup list, where it can be listed and downloaded after the subgraph is gone. If the backup fails the subgraph is not deleted.

Default: true

Example request

curl

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/operations/delete-subgraph" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "subgraph_name": "string"
}'

Responses

200 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
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