Skip to main content

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 pathhttps://<your-host>/api/v1/context-graph
AuthenticationAuthorization: Bearer <token>, with a personal access token (ahpat_…) or a service account key (ahsa_…). See API credentials.
ProjectEvery request needs project_id as a query parameter. Each project has its own graph.
PermissionsThe credential's roles on that project. See the Context Graph permissions in Roles.
Rate limits60 requests per minute per credential, 600 per minute per organization
PaginationList 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:

BASH
autoheal api GET /api/v1/context-graph/blueprints --query project_id=$PROJECT_ID

Blueprints​

MethodPathDescription
GET/blueprintsList system, integration and custom blueprints.
POST/blueprintsCreate 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:

BASH
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​

MethodPathDescription
GET/blueprints/{blueprint}/entitiesList a blueprint's entities. Query: search (name and title, not case-sensitive), source (an integration type), limit, offset.
POST/blueprints/{blueprint}/entitiesCreate 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/entitiesList entities of every blueprint.
GET/entities/{entity_id}Get an entity by ID.
GET/entities/{entity_id}/sourcesThe source records linked to an entity, and the source of each field and relation.

An entity has these fields:

FieldDescription
idThe entity's ID.
nameThe canonical name. Unique in its blueprint and project, and cannot change. Labels match this value.
titleThe display name. Also unique in its blueprint and project.
blueprintThe blueprint name.
propertiesValues for the blueprint's properties. Checked against the blueprint schema.
relationsRelation key to a target name, or a list of names for a many relation.
labelsLabel key to a list of values.
warningsSOFT_LINK_UNRESOLVED when a relation names a target that does not exist yet.
createdAt, createdBy, updatedAt, updatedByWhen and by whom the entity changed.

Create or update a service and its owner:

BASH
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​

MethodPathDescription
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-linksEntities with relations whose targets do not exist yet.

Add a contributor with a role:

BASH
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.

MethodPathDescription
GET/nodesFind starting points by name or title. Query: search, limit (1 to 50, default 20).
GET/neighborhoodThe graph around one root. Query: root_kind, root_id, depth (0 to 5, default 2), and the filters below.
GET/overviewA 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/filtersThe node kinds, edge kinds, blueprints and relation keys you can filter on.
GET/label-targetsFor 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.

BASH
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​

MethodPathDescription
POST/syncsStart 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/syncsList 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​

MethodPathDescription
GET/integrations/{integration_id}/sync-settingsThe connection's filters, target project, and mode for each entity type.
POST/integrations/{integration_id}/sync-settings/previewWhat a settings change would add, link, mark stale and remove. Changes nothing.
PUT/integrations/{integration_id}/sync-settingsSave the settings. The next sync uses them.
JSON
{
"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 full run says "this is everything this source has". After the run completes, entities the source sent before and left out this time become stale.
  • A delta run only creates and updates.
MethodPathDescription
POST/sources/{source}/runsStart a run. Body: {mode: "full" | "delta"}. Returns {run_id}.
POST/sources/{source}/runs/{run_id}/entitiesSend up to 1,000 entities. Call it as many times as you need.
POST/sources/{source}/runs/{run_id}/completeFinish the run. A full run marks missing entities stale now.
GET/sources/{source}/runs/{run_id}The run's status and counts.
BASH
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​

MethodPathDescription
GET/suggestionsList suggestions. Query: status (pending, accepted, rejected), blueprint, kind (link, field, relation).
POST/suggestions/{suggestion_id}/acceptApply the suggestion.
POST/suggestions/{suggestion_id}/rejectClose the suggestion without applying it. The resolver does not suggest the same change again.

See The review queue.

Error codes​

CodeHTTPMeaning
14000404Blueprint not found.
14001409A blueprint with this name already exists.
14002409The blueprint has entities and cannot be deleted.
14003400The blueprint schema is not valid.
14004403System and integration blueprints cannot be changed.
14008400The relations definition is not valid, for example a relation target that is not a blueprint in the project.
14009409The blueprint name is reserved: a system or integration blueprint, or a graph node kind.
14010400The blueprint name is not valid.
14011400The icon is not a Phosphor icon name.
14100404Entity not found.
14101409An entity with this name already exists.
14102400A property does not match the blueprint schema.
14103400A relation is not valid.
14104409Other entities refer to this entity. Use force=true to delete it anyway.
14108400The relation's target does not exist. Send allowSoftLinks: true to keep it unresolved.
14109400The relation's target has the wrong blueprint.
14110400A required relation is missing.
14111400A one-target relation got more than one target.
14112400The blueprint has no relation with this key.
14113409The entity title conflicts with another entity.
14200404The graph root was not found in the project.
14201400A graph query parameter is not valid.
14202500A source of the graph could not be read.
22400404The project was not found, or is not in your organization.
22405422project_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.