> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/workspaces/context-graphs.md).

# Context Graphs

Author workspace-scoped Context Graphs and immutable versions, bind workflow tools, and select a graph version through a service release configuration.

A Context Graph defines the states, guidance, transitions, and workflow tool bindings for an agent. Create a named graph, add a version with its state definitions, and select that version in a [service](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md). Updating the graph's name or description does not publish a new state configuration.

For the concepts and trade-offs, read [Context Graphs](https://docs.concurrence.com/agent/context-graphs). For complete runnable configuration, use [Create a Test Service](https://docs.concurrence.com/developer-guide/guides/create-a-test-service.md).

## Authoring Workflow

1. Create the graph in the intended workspace and retain its ID.
2. Create a version with its states, new-user and returning-user initial states, and, optionally, a terminal state. A version without a terminal state never ends a conversation on navigation. See [Terminal State & Auto-Hangup](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#terminal-state-and-auto-hangup). Supported state types are action, decision, annotation, and data collection.
3. Read the returned version by number and inspect its state and tool configuration. Version creation is separate from service selection.
4. Pin that number in the service's selected version set, alongside the intended [agent version](https://docs.concurrence.com/developer-guide/platform-api/workspaces/agents.md). Read back the service selection before testing.
5. Evaluate the workflow and external outcomes with [Build and Prove](https://docs.concurrence.com/developer-guide/guides/build-and-prove.md) before promoting a candidate.

Graph instructions guide model behavior and do not make responses deterministic. State bindings govern workflow tools, while service and channel configuration can also expose supported tools. Review effective permissions and test targets in addition to the graph.

## Permissions and Recovery

Use a credential accepted for the workspace. Reading requires graph-view permission. Creating the first version uses graph-create permission, and subsequent versions require graph-update permission. Metadata updates and deletion also require their respective permissions.

Keep the graph ID and acknowledged version number after every write. If version creation returns a conflict or the response is lost, read the current versions and compare their configuration before submitting another write. Do not infer that a failed client request means no version exists.

Deletion is refused while services reference the graph. Update or delete those service references first, after checking that they are not shared with another workflow. Configuration cleanup does not erase a conversation's retained evidence.

## Operations

### Create a graph

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/context-graphs" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### List graphs

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/context-graphs" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get a graph

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/context-graphs/{context\_graph\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Update graph metadata

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/context-graphs/{context\_graph\_id}" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Delete a graph

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/context-graphs/{context\_graph\_id}" method="delete" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Create a version

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/context-graphs/{context\_graph\_id}/versions" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### List versions

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/context-graphs/{context\_graph\_id}/versions" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get a version

Use a numeric version for a specific configuration or `latest` to inspect the most recent version.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/context-graphs/{context\_graph\_id}/versions/{version}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/workspaces/context-graphs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
