# Create convo URL: https://docs.hanzo.ai/docs/openapi/graph/graphconvo > Extracts entity state and relationship assertions from conversation turns and updates the graph. `POST /v1/graph/convo` > [Graph →](https://docs.hanzo.ai/docs/openapi/graph) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/graph/convo` | | **Method** | `POST` | | **Operation** | `graphConvo` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Extracts entity state and relationship assertions from conversation turns and updates the graph. First-person statements bind to the turn's speaker, second-person statements to its partner, and named subjects to their entity keys. Questions are skipped. Single-valued state updates (such as moving cities or changing roles) supersede prior values at the turn's timestamp, and explicit departures (such as leaving an employer) file a retraction ending the prior claim. Set dry\_run to inspect what the turns state without writing. Time: each turn's at (or the batch's at when omitted) is the valid instant of the assertions extracted from it, which an as\_of read is bounded by; each becomes knowable at the write, which an as\_known read is bounded by. ## Request 9 fields, body `application/json` (required). | Field | In | Type | Required | Description | | ----------------- | ---- | ------------------ | -------- | ----------------------------------------------------------------------------------------------------- | | `at` | body | string | yes | At is the default valid instant for any turn that omits its own At, RFC 3339. | | `dry_run` | body | boolean | — | DryRun when true returns the extracted assertions without writing them to the store. | | `source` | body | string | yes | Source names the conversation these turns came from, such as chat/thread-42. | | `turns` | body | graph.graphTurn\[] | yes | Turns is the ordered dialogue turns to read. | | `turns[].at` | body | string | — | At is when this turn was spoken, RFC 3339. | | `turns[].id` | body | string | — | ID is the turn's identifier within the conversation, appended to Source as `#<id>` in Evidence. | | `turns[].partner` | body | string | — | Partner is the entity key of the participant addressed in this turn. | | `turns[].speaker` | body | string | yes | Speaker is the entity key of the participant speaking this turn. | | `turns[].text` | body | string | yes | Text is what the speaker said. | ## Response | Status | Body | Meaning | | --------- | ------------------- | ------- | | `200` | graph.graphConvoOut | ok | | `default` | problem-details | refused | `200` body — 15 fields. | Field | In | Type | Always | Description | | ------------------------- | ---- | ------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | | `assertions` | body | graph.graphFact\[] | — | Assertions is the assertions extracted from the turns, in turn order. | | `assertions[].at` | body | string | yes | At is when the thing was so, RFC 3339. | | `assertions[].confidence` | body | number (double) | — | Confidence in \[0,1]. | | `assertions[].entity` | body | string | yes | Entity is the thing being described, in the organization's own namespace. | | `assertions[].evidence` | body | string | — | Evidence points at the record this claim came from, 512 bytes at most. | | `assertions[].names` | body | boolean | — | Names says the value is an entity. | | `assertions[].relation` | body | string | yes | Relation is what is being asserted — `depends`, `owner`, `same`, `title` — and a key, folded as Entity is. | | `assertions[].seen` | body | string | — | Seen is when this assertion became knowable, RFC 3339. | | `assertions[].source` | body | string | yes | Source names who asserted. | | `assertions[].until` | body | string | — | Until is when the thing stopped being so, RFC 3339, and must follow At. | | `assertions[].value` | body | string | — | Value is what the relation points at. | | `duplicate` | body | integer (int64) | — | Duplicate is how many extracted assertions the store already held. | | `reasons` | body | string\[] | — | Reasons names why each refused assertion was refused, in order. | | `recorded` | body | integer (int64) | — | Recorded is how many extracted assertions became new rows in the store. | | `refused` | body | integer (int64) | — | Refused is how many extracted assertions were refused by admission or schema checks. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo graph convo \ --at \ --source \ --turns '[{"speaker":"","text":""}]' ``` **SDK** **.ts** ```ts import { Configuration, GraphApi } from 'hanzoai'; const api = new GraphApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.graphConvo({ source: "", at: "", turns: [{"speaker":"","text":""}] }); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import GraphApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = GraphApi(client).graph_convo(source="", at="", turns=[{"speaker":"","text":""}]) ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.GraphAPI.GraphConvo(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, graph_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = graph_api::graph_convo(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.GraphApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new GraphApi(client).graphConvo(); ``` The method above is the one at the current release of the document. `hanzoai@8.5.914` (npm) and `hanzoai@8.5.914` (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. [SDKs →](https://docs.hanzo.ai/docs/sdks) **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/graph/convo \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source": "", "at": "", "turns": [ { "speaker": "", "text": "" } ] }' ``` **MCP** Tool `graph`, op `graphConvo` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`. ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "graph", "arguments": { "op": "graphConvo", "input": { "source": "", "at": "", "turns": [ { "speaker": "", "text": "" } ] } } } }' ``` --- [Graph API](https://docs.hanzo.ai/docs/openapi/graph) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)