Context Graph API
The Context Graph API is the same API the Autoheal web app uses. Use it to manage blueprints and entities from scripts, to read the graph from your own tools, and to push entities from systems that Autoheal does not integrate with.
Before you start
| Base path | https://<your-host>/api/v1/context-graph |
| Authentication | Authorization: Bearer <token>, with a personal access token (ahpat_…) or a service account key (ahsa_…). See API credentials. |
| Project | Every request needs project_id as a query parameter. Each project has its own graph. |
| Permissions | The credential's roles on that project. See the Context Graph permissions in Roles. |
| Rate limits | 60 requests per minute per credential, 600 per minute per organization |
| Pagination | List endpoints take limit (1 to 100, default 100) and offset, and return {items, total, limit, offset}. |
| Errors | {code, message, details}. See Error codes. |
The CLI calls any endpoint with autoheal api:
autoheal api GET /api/v1/context-graph/blueprints --query project_id=$PROJECT_ID
Blueprints
| Method | Path | Description |
|---|---|---|
GET | /blueprints | List system, integration and custom blueprints. |
POST | /blueprints | Create a custom blueprint. |
GET | /blueprints/{blueprint} | Get one blueprint. |
PUT | /blueprints/{blueprint} | Update a custom blueprint's title, description, icon, schema or relations. System and integration blueprints answer 403. |
DELETE | /blueprints/{blueprint} | Delete a custom blueprint that has no entities. A blueprint with entities answers 409. |
Create a blueprint:
curl -X POST "https://acme.autoheal.ai/api/v1/context-graph/blueprints?project_id=$PROJECT_ID" \
-H "Authorization: Bearer $AUTOHEAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "environment",
"title": "Environment",
"description": "A place where services run",
"icon": "globe",
"schema": {
"properties": {
"region": {"type": "string", "title": "Region"},
"stage": {"type": "string", "title": "Stage", "enum": ["dev", "staging", "prod"]}
},
"required": ["stage"]
},
"relations": {
"services": {"title": "Services", "target": "service", "many": true}
}
}'
The response is the blueprint, with scope set to system for built-in and integration blueprints and organization for yours. See Blueprints for every schema field.
Entities
| Method | Path | Description |
|---|---|---|
GET | /blueprints/{blueprint}/entities | List a blueprint's entities. Query: search (name and title, not case-sensitive), source (an integration type), limit, offset. |
POST | /blueprints/{blueprint}/entities | Create an entity. An entity with the same name answers 409. |
GET | /blueprints/{blueprint}/entities/{entity} | Get one entity by name. |
PUT | /blueprints/{blueprint}/entities/{entity} | Create or update an entity. Answers 201 when created and 200 when updated. |
PATCH | /blueprints/{blueprint}/entities/{entity} | Change properties, the title or labels only. Properties you send replace those keys, and other properties stay. Omit labels to keep them. Send labels to replace them all. |
DELETE | /blueprints/{blueprint}/entities/{entity} | Delete an entity. If other entities refer to it, the call answers 409. Add force=true to delete it anyway. |
GET | /entities | List entities of every blueprint. |
GET | /entities/{entity_id} | Get an entity by ID. |
GET | /entities/{entity_id}/sources | The source records linked to an entity, and the source of each field and relation. |
An entity has these fields:
| Field | Description |
|---|---|
id | The entity's ID. |
name | The canonical name. Unique in its blueprint and project, and cannot change. Labels match this value. |
title | The display name. Also unique in its blueprint and project. |
blueprint | The blueprint name. |
properties | Values for the blueprint's properties. Checked against the blueprint schema. |
relations | Relation key to a target name, or a list of names for a many relation. |
labels | Label key to a list of values. |
warnings | SOFT_LINK_UNRESOLVED when a relation names a target that does not exist yet. |
createdAt, createdBy, updatedAt, updatedBy | When and by whom the entity changed. |
Create or update a service and its owner:
curl -X PUT "https://acme.autoheal.ai/api/v1/context-graph/blueprints/service/entities/checkout?project_id=$PROJECT_ID" \
-H "Authorization: Bearer $AUTOHEAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Checkout",
"properties": {"tier": "tier-1", "language": "go"},
"relations": {"owner": "payments", "depends_on": ["ledger", "fraud-score"]},
"allowSoftLinks": true
}'
A value you set through the API is declared: it has the highest rank, and a sync does not overwrite it. See Field precedence.
allowSoftLinks: true keeps a relation whose target does not exist yet. Without it, the call answers 400 with code 14108.
Relations
| Method | Path | Description |
|---|---|---|
GET | /blueprints/{blueprint}/entities/{entity}/relations/{key} | List one relation's targets, with relation properties. |
POST | /blueprints/{blueprint}/entities/{entity}/relations/{key} | Add a target. Body: {target, properties, allowSoftLinks}. Adding a target that is already there answers 200. |
DELETE | /blueprints/{blueprint}/entities/{entity}/relations/{key}/{target} | Remove one target. |
GET | /soft-links | Entities with relations whose targets do not exist yet. |
Add a contributor with a role:
curl -X POST "https://acme.autoheal.ai/api/v1/context-graph/blueprints/service/entities/checkout/relations/contributors?project_id=$PROJECT_ID" \
-H "Authorization: Bearer $AUTOHEAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"target": "dana", "properties": {"role": "tech lead"}}'
Graph reads
These endpoints read the graph as nodes and edges, including label associations to skills, agents, memories, artifacts and integrations. They need permission to see blueprints and entities, and each other node kind needs its own read permission. A kind you cannot read is left out.
| Method | Path | Description |
|---|---|---|
GET | /nodes | Find starting points by name or title. Query: search, limit (1 to 50, default 20). |
GET | /neighborhood | The graph around one root. Query: root_kind, root_id, depth (0 to 5, default 2), and the filters below. |
GET | /overview | A bounded view of the whole project: up to 2,000 nodes and 6,000 edges, with a fair share for each blueprint. Takes the filters below. |
GET | /filters | The node kinds, edge kinds, blueprints and relation keys you can filter on. |
GET | /label-targets | For each blueprint, the entity names a label can name. Query: limit (1 to 500, default 200). |
Filters are comma-separated allow-lists: node_kinds, blueprints, edge_kinds, relation_keys, memory_statuses. An omitted list allows everything. An empty list allows nothing. branch selects the Git branch for skills and agents.
autoheal api GET /api/v1/context-graph/neighborhood \
--query project_id=$PROJECT_ID \
--query root_kind=entity --query root_id=$ENTITY_ID \
--query depth=2 --query edge_kinds=relation
A response has nodes, edges, truncation, unavailableSources and diagnostics. diagnostics lists labels that name a blueprint but no entity. See Agent tools for a sample response.
Syncs
| Method | Path | Description |
|---|---|---|
POST | /syncs | Start a sync. Body: {integration_id} for one integration connection, {blueprint} for one entity type across its sources, or both. Answers 202 with {sync_id, status}. status is queued, or already_running when the same sync is in progress. |
GET | /syncs | List recent syncs. Query: integration_id, blueprint, status, limit, offset. |
GET | /syncs/{sync_id} | One sync's status and counts. |
A sync has status (queued, running, succeeded, partial, failed), trigger (connect, event, schedule, manual), startedAt, completedAt, counts (created, updated, linked, stale, removed) and errors. Starting a sync needs permission to update the integration.
Sync settings
| Method | Path | Description |
|---|---|---|
GET | /integrations/{integration_id}/sync-settings | The connection's filters, target project, and mode for each entity type. |
POST | /integrations/{integration_id}/sync-settings/preview | What a settings change would add, link, mark stale and remove. Changes nothing. |
PUT | /integrations/{integration_id}/sync-settings | Save the settings. The next sync uses them. |
{
"targetProjectId": "6b7c…",
"entityTypes": {
"pagerduty_service": {"mode": "keep_in_sync"},
"pagerduty_team": {"mode": "keep_in_sync"},
"pagerduty_person": {"mode": "off"}
},
"filters": {
"teams": ["Payments", "Platform"]
}
}
mode is keep_in_sync, sync_once or off. The filters each integration supports are listed in Sync integrations.
Push API
Push entities from your own systems. Each system is a named source. Pushes are grouped into a run:
- A
fullrun says "this is everything this source has". After the run completes, entities the source sent before and left out this time become stale. - A
deltarun only creates and updates.
| Method | Path | Description |
|---|---|---|
POST | /sources/{source}/runs | Start a run. Body: {mode: "full" | "delta"}. Returns {run_id}. |
POST | /sources/{source}/runs/{run_id}/entities | Send up to 1,000 entities. Call it as many times as you need. |
POST | /sources/{source}/runs/{run_id}/complete | Finish the run. A full run marks missing entities stale now. |
GET | /sources/{source}/runs/{run_id} | The run's status and counts. |
RUN=$(curl -s -X POST "https://acme.autoheal.ai/api/v1/context-graph/sources/internal-cmdb/runs?project_id=$PROJECT_ID" \
-H "Authorization: Bearer $AUTOHEAL_TOKEN" -H "Content-Type: application/json" \
-d '{"mode": "full"}' | jq -r .run_id)
curl -X POST "https://acme.autoheal.ai/api/v1/context-graph/sources/internal-cmdb/runs/$RUN/entities?project_id=$PROJECT_ID" \
-H "Authorization: Bearer $AUTOHEAL_TOKEN" -H "Content-Type: application/json" \
-d '[
{"blueprint": "service", "name": "billing", "title": "Billing",
"properties": {"tier": "tier-2"},
"relations": {"owner": "finance-eng"}}
]'
curl -X POST "https://acme.autoheal.ai/api/v1/context-graph/sources/internal-cmdb/runs/$RUN/complete?project_id=$PROJECT_ID" \
-H "Authorization: Bearer $AUTOHEAL_TOKEN"
Values from the push API are declared. The resolver links pushed entities to existing ones by the blueprint's identity rules, the same as integration records.
Review queue
| Method | Path | Description |
|---|---|---|
GET | /suggestions | List suggestions. Query: status (pending, accepted, rejected), blueprint, kind (link, field, relation). |
POST | /suggestions/{suggestion_id}/accept | Apply the suggestion. |
POST | /suggestions/{suggestion_id}/reject | Close the suggestion without applying it. The resolver does not suggest the same change again. |
See The review queue.
Error codes
| Code | HTTP | Meaning |
|---|---|---|
| 14000 | 404 | Blueprint not found. |
| 14001 | 409 | A blueprint with this name already exists. |
| 14002 | 409 | The blueprint has entities and cannot be deleted. |
| 14003 | 400 | The blueprint schema is not valid. |
| 14004 | 403 | System and integration blueprints cannot be changed. |
| 14008 | 400 | The relations definition is not valid, for example a relation target that is not a blueprint in the project. |
| 14009 | 409 | The blueprint name is reserved: a system or integration blueprint, or a graph node kind. |
| 14010 | 400 | The blueprint name is not valid. |
| 14011 | 400 | The icon is not a Phosphor icon name. |
| 14100 | 404 | Entity not found. |
| 14101 | 409 | An entity with this name already exists. |
| 14102 | 400 | A property does not match the blueprint schema. |
| 14103 | 400 | A relation is not valid. |
| 14104 | 409 | Other entities refer to this entity. Use force=true to delete it anyway. |
| 14108 | 400 | The relation's target does not exist. Send allowSoftLinks: true to keep it unresolved. |
| 14109 | 400 | The relation's target has the wrong blueprint. |
| 14110 | 400 | A required relation is missing. |
| 14111 | 400 | A one-target relation got more than one target. |
| 14112 | 400 | The blueprint has no relation with this key. |
| 14113 | 409 | The entity title conflicts with another entity. |
| 14200 | 404 | The graph root was not found in the project. |
| 14201 | 400 | A graph query parameter is not valid. |
| 14202 | 500 | A source of the graph could not be read. |
| 22400 | 404 | The project was not found, or is not in your organization. |
| 22405 | 422 | project_id is missing. |
401 means the credential is not valid. 403 means the credential's roles do not allow the call. 429 means you reached the rate limit.