Connect

API

Vinc REST v1 reads and writes your account graph over HTTP. It suits places where MCP or a framework package is awkward, such as a server or a batch job.

Quickstart

Make a key on your vincs.io account page, then call the API with it. The base URL is https://mcp.vincs.io and every route starts with /v1.

export VINC_API_KEY=vinc_ro_...

# Which graph am I on
curl -H "Authorization: Bearer $VINC_API_KEY" https://mcp.vincs.io/v1/me

# Search
curl -X POST https://mcp.vincs.io/v1/search \
  -H "Authorization: Bearer $VINC_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "release checklist", "limit": 5}'

# Store a document (needs a vinc_sk_ key)
curl -X POST https://mcp.vincs.io/v1/documents \
  -H "Authorization: Bearer $VINC_WRITE_KEY" -H "Content-Type: application/json" \
  -d '{"text": "# Notes\n...", "title": "Meeting notes"}'

This API reaches your account graph. The desktop app's local mode is not reachable over HTTP; use the CLI there. From Python, vincs wraps these routes.

Authentication and space

Send the key in an Authorization: Bearer <key> header, never in the URL. A vinc_ro_ key reads; a vinc_sk_ key can also write. Each operation below says which it needs. Add space=<team id> to reach a team's graph; without it you reach your personal graph.

Requests and pages

Send Content-Type: application/json with a request body. Responses are JSON. A list that has more carries has_more and next_cursor; pass that cursor to get the next page. Do not make up a cursor, and if one has expired, start over on purpose rather than quietly.

Errors

An error response has an error object with code, message, request_id and details.

Status	Meaning
`400`	The request was malformed.
`401`	The key is missing or wrong.
`403`	The key cannot do this, for example a read-only key writing.
`404`	No such route, node or document.
`405`	Wrong method for this route.
`409`	The request no longer matches the current state, for example an edit made from an older read, or a pinned role that has changed (`role_changed`).
`413`	The body is too large.
`429`	The daily limit is used up. Wait the `Retry-After` seconds. `Vinc-Quota-Limit` gives the number of calls a day allows, and `Vinc-Quota-Remaining` is `0`. MCP and REST calls count against the same limit.
`500`	Server error.
`503`	A service behind the API is unavailable.

Before retrying a write that failed with 500, check details.tool_ran. If it is true the write may already have happened, so read it back first.

A Community 503 response with details.write_may_have_applied=true leaves the result unconfirmed. Read its saved revision or mutation receipt before retrying. Keep the same mutationId for actions that support it. A 409 edit conflict keeps the original draft and requires reviewing the current revision before another save.

36 operations

Methods, paths, parameters and success statuses come straight from the OpenAPI document, which also has the full response shapes.

About this connection

Graph identity and spaces

GET /v1/me Read key

See the current graph owner, scope and team spaces.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Writing conventions

GET /v1/conventions Read key

Read the graph's authoring rules before a write.

Parameter	In	Type	Meaning
`lang`	query	string	Language of the default template: `en` or `ko`. Ignored once you wrote your own GRAPH.md.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Domain counts

GET /v1/domains Read key

List domains and counts by node kind.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

OpenAPI document

GET /v1/openapi.json Read key

Download the machine-readable API contract.

Success: 200

Write results

Check a write result

GET /v1/operations/{operation_id} Read key

Read this space's historical operation receipt. accepted or unknown is uncertain; committed proves a graph transaction, not published persistence. Read current targets before deciding what to do next.

Parameter	In	Type	Meaning
`operation_id` *	path	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Agent roles

List agent roles

GET /v1/roles Read key

List the roles available in the selected space without reading full contracts.

Parameter	In	Type	Meaning
`limit`	query	integer	How many results.
`offset`	query	integer	Roster candidate offset from `next_offset`; defaults to 0.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Read a role contract

GET /v1/roles/{id} Read key

Read one role's permissions, collaboration links and rendered contract by its slug or exact concept ID. The contract carries its rev and hash; pass the hash as expected_hash to get the contract only while the role is unchanged.

Parameter	In	Type	Meaning
`id` *	path	string	A node id, such as `concept:design-token`.
`expected_hash`	query	string	The contract `hash` from an earlier read of this role. If the role has changed since, the answer is `409` `role_changed` with no contract, and `details` holds the current `rev` and `hash`.
`expected_rev`	query	integer	The role's `rev` from an earlier read. A different revision answers `409` `role_changed`, like `expected_hash`.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Check an answer against a role

POST /v1/roles/{id}/check Read key

Check one final answer against a role's structured checks before it goes out. Returns pass, block or interrupt. A claim that something already ran is always blocked here, because this call cannot take evidence from the caller.

Parameter	In	Type	Meaning
`id` *	path	string	A node id, such as `concept:design-token`.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`output` *	body	string	The complete answer to check, at most 131072 characters.
`person_only_requests`	body	array	Requests in the answer for a person to decide, each `{action, reason}`. The action must be one of the role's person-only actions.
`self_authored`	body	boolean	`true` when the answer is a diff the role wrote. Removed lines are then not read as proposals.

Success: 200

Searching and reading

Search

POST /v1/search Read key

Search documents and nodes with cursor pagination.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`query` *	body	string	The question or search text.
`limit`	body	integer	How many results.
`cursor`	body	string	`next_cursor` from the previous page.
`detail`	body	string	`summary` or `full`.
`historical`	body	boolean	Also include claims that are no longer current.
`as_of`	body	string	Select validity intervals overlapping `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, with the end excluded. This does not restore earlier body revisions.
`known_at`	body	string	Read what the graph had recorded by `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, independently of validity time. This is an initial creation cutoff, not restoration of an older body revision. Nodes without a stored creation time remain and are counted as unknown.
`mode`	body	string	Optional `general`, `current` or `historical`. General keeps the default. Current excludes future and expired evidence but keeps unknown dates and reports conflicts; it cannot be combined with `historical=true` or `as_of`. Historical keeps past evidence accessible.

Success: 200

Brief for a question

POST /v1/brief Read key

Retrieve one resolved node, excerpts and relations for a question.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`query` *	body	string	The question or search text.
`max_excerpts`	body	integer	How many document excerpts to attach.
`historical`	body	boolean	Also include claims that are no longer current.
`as_of`	body	string	Select validity intervals overlapping `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, with the end excluded. This does not restore earlier body revisions.
`known_at`	body	string	Read what the graph had recorded by `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, independently of validity time. This is an initial creation cutoff, not restoration of an older body revision. Nodes without a stored creation time remain and are counted as unknown.
`mode`	body	string	Optional `general`, `current` or `historical`. General keeps the default. Current excludes future and expired evidence but keeps unknown dates and reports conflicts; it cannot be combined with `historical=true` or `as_of`. Historical keeps past evidence accessible.

Success: 200

Exact node

GET /v1/nodes/{id} Read key

Read the complete node stored at an exact ID.

Parameter	In	Type	Meaning
`id` *	path	string	A node id, such as `concept:design-token`.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Directed edges

GET /v1/nodes/{id}/edges Read key

Read incident edges with direction, type and evidence, including structural edges.

Parameter	In	Type	Meaning
`id` *	path	string	A node id, such as `concept:design-token`.
`type`	query	string	`relates_to`, `prerequisite_of`, `derives_from`, `inherits_from`, `returns_to`, `about` or `ATTACHES_TO`. Record edges accept their authored type or `ATTACHES_TO`; `returns_to` connects roles only.
`dir`	query	string	Edge direction: `out`, `in` or `both`.
`limit`	query	integer	How many results.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Edges for several nodes

POST /v1/edges/query Read key

Read directed edges for a bounded list of exact node IDs in one call.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`nodes` *	body	array	Nodes matched by id. Optional expected_rev checks the revision from an exact read for the entire fragment before writing. props_patch requires expected_rev and excludes props: nested objects merge, null removes keys, arrays replace. Omitted props preserves it; props replaces the stored value.
`type`	body	string	`relates_to`, `prerequisite_of`, `derives_from`, `inherits_from`, `returns_to`, `about` or `ATTACHES_TO`. Record edges accept their authored type or `ATTACHES_TO`; `returns_to` connects roles only.
`dir`	body	string	Edge direction: `out`, `in` or `both`.
`limit`	body	integer	How many results.

Success: 200

Neighbors

GET /v1/nodes/{id}/neighbors Read key

Read the immediate relations of one node.

Parameter	In	Type	Meaning
`id` *	path	string	A node id, such as `concept:design-token`.
`limit`	query	integer	How many results.
`as_of`	query	string	Select validity intervals overlapping `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, with the end excluded. This does not restore earlier body revisions.
`known_at`	query	string	Read what the graph had recorded by `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, independently of validity time. This is an initial creation cutoff, not restoration of an older body revision. Nodes without a stored creation time remain and are counted as unknown.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Graph around a node

GET /v1/nodes/{id}/graph Read key

Read a bounded graph around an exact node ID.

Parameter	In	Type	Meaning
`id` *	path	string	A node id, such as `concept:design-token`.
`depth`	query	integer	How many steps out to go (1 to 4).
`select`	query	string	How to choose nodes when there are too many: `layers` or `prize`.
`review_mirror`	query	boolean	Set `true` with one exact `concept:doc.<doc_id>` node to include a read-only `mirror_review` of its source provenance. No links are changed. Omit it for the usual graph response.
`as_of`	query	string	Select validity intervals overlapping `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, with the end excluded. This does not restore earlier body revisions.
`known_at`	query	string	Read what the graph had recorded by `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, independently of validity time. This is an initial creation cutoff, not restoration of an older body revision. Nodes without a stored creation time remain and are counted as unknown.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Graph for a View URL

POST /v1/graph Read key

Read the graph selected by a View address.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`url`	body	string	A View address copied from the app, in place of a node id.
`depth`	body	integer	How many steps out to go (1 to 4).
`select`	body	string	How to choose nodes when there are too many: `layers` or `prize`.
`review_mirror`	body	boolean	Set `true` with one exact `concept:doc.<doc_id>` node to include a read-only `mirror_review` of its source provenance. No links are changed. Omit it for the usual graph response.
`as_of`	body	string	Select validity intervals overlapping `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, with the end excluded. This does not restore earlier body revisions.
`known_at`	body	string	Read what the graph had recorded by `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, independently of validity time. This is an initial creation cutoff, not restoration of an older body revision. Nodes without a stored creation time remain and are counted as unknown.

Success: 200

Path between nodes

GET /v1/path Read key

Find a relation path between two nodes.

Parameter	In	Type	Meaning
`a` *	query	string	The first concept id.
`b` *	query	string	The second concept id.
`max_depth`	query	integer	Longest path to look for, in steps.
`weight`	query	string	Measure distance by link count or by evidence strength.
`as_of`	query	string	Select validity intervals overlapping `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, with the end excluded. This does not restore earlier body revisions.
`known_at`	query	string	Read what the graph had recorded by `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, independently of validity time. This is an initial creation cutoff, not restoration of an older body revision. Nodes without a stored creation time remain and are counted as unknown.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Possible connections

GET /v1/nodes/{id}/tie-suggestions Read key

Find candidate relations for one node.

Parameter	In	Type	Meaning
`id` *	path	string	A node id, such as `concept:design-token`.
`limit`	query	integer	How many results.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Recall episodes

GET /v1/episodes Read key

Retrieve past work episodes.

Parameter	In	Type	Meaning
`domain`	query	string	Only this topic.
`tags`	query	array	Only episodes with these tags.
`limit`	query	integer	How many results.
`cursor`	query	string	`next_cursor` from the previous page.
`as_of`	query	string	Select validity intervals overlapping `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, with the end excluded. This does not restore earlier body revisions.
`known_at`	query	string	Read what the graph had recorded by `YYYY`, `YYYY-MM` or `YYYY-MM-DD`, independently of validity time. This is an initial creation cutoff, not restoration of an older body revision. Nodes without a stored creation time remain and are counted as unknown.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Decision support

GET /v1/decide Read key

Gather graph evidence for a decision question.

Parameter	In	Type	Meaning
`topic` *	query	string	The topic to decide on, or the topic to file a document under.
`depth`	query	integer	How many steps out to go (1 to 4).
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Graph diagnosis

GET /v1/diagnose Read key

Inspect graph health and structural findings.

Parameter	In	Type	Meaning
`kind`	query	string	What to check: `components`, `communities`, `community_context` or `claims`.
`node`	query	string	The concept to centre on, with `community_context`.
`member_limit`	query	integer	How many member ids to list per group.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Documents

List documents

GET /v1/documents Read key

List document identities and continue with a cursor.

Parameter	In	Type	Meaning
`limit`	query	integer	How many results.
`cursor`	query	string	`next_cursor` from the previous page.
`detail`	query	string	`summary` or `full`.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Read a document

GET /v1/documents/{doc_id} Read key

Read canonical text and check its integrity flag.

Parameter	In	Type	Meaning
`doc_id` *	path	string	A document id.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Create a document

POST /v1/documents Write key

Store a new canonical document.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`text` *	body	string	The full text of the document.
`title`	body	string	Leave it out to keep the current title; send `""` to clear it.
`origin`	body	string	Where the text came from. For display only.
`topic`	body	string	The topic to decide on, or the topic to file a document under.
`content_time`	body	string	When the thing the document describes happened, as opposed to when it was written: `YYYY`, `YYYY-MM` or `YYYY-MM-DD`. Omit to keep the stored value; an empty string clears it.
`valid_from`	body	string	When the document became valid: `YYYY`, `YYYY-MM` or `YYYY-MM-DD`. Omit to keep the stored value; an empty string clears it.
`valid_until`	body	string	When the document stopped being valid, with the end excluded. Retires it from default search without deleting it; `historical=true` or an applicable `as_of` period can still find it. Omit to keep; an empty string clears it.
`superseded_by`	body	string	The `doc_id` of the document that replaced this one. Omit to keep the stored value; an empty string clears it.
`expected_content_hash`	body	string	Hash from the previous document read. If it differs, the edit conflicts before mutation. Empty string requires an absent document.
`create_only`	body	boolean	Refuse an existing identity before any write. Omit to keep the existing add-or-update behavior.
`operation_id`	body	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.

Success: 201

Update a document

PUT /v1/documents/{doc_id} Write key

Replace the canonical text of an exact document ID.

Parameter	In	Type	Meaning
`doc_id` *	path	string	A document id.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`text` *	body	string	The full text of the document.
`title`	body	string	Leave it out to keep the current title; send `""` to clear it.
`origin`	body	string	Where the text came from. For display only.
`topic`	body	string	The topic to decide on, or the topic to file a document under.
`content_time`	body	string	When the thing the document describes happened, as opposed to when it was written: `YYYY`, `YYYY-MM` or `YYYY-MM-DD`. Omit to keep the stored value; an empty string clears it.
`valid_from`	body	string	When the document became valid: `YYYY`, `YYYY-MM` or `YYYY-MM-DD`. Omit to keep the stored value; an empty string clears it.
`valid_until`	body	string	When the document stopped being valid, with the end excluded. Retires it from default search without deleting it; `historical=true` or an applicable `as_of` period can still find it. Omit to keep; an empty string clears it.
`superseded_by`	body	string	The `doc_id` of the document that replaced this one. Omit to keep the stored value; an empty string clears it.
`expected_content_hash`	body	string	Hash from the previous document read. If it differs, the edit conflicts before mutation. Empty string requires an absent document.
`create_only`	body	boolean	Refuse an existing identity before any write. Omit to keep the existing add-or-update behavior.
`operation_id`	body	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.

Success: 200, 201

Extract concepts

POST /v1/documents/{doc_id}/extract Write key

Propose concepts from a document, then apply only when requested.

Parameter	In	Type	Meaning
`doc_id` *	path	string	A document id.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`apply`	body	boolean	`false` only previews; `true` writes the concepts.
`candidates`	body	array	Your own list of concepts to write instead of the extracted ones.
`operation_id`	body	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.

Success: 200

Delete a document

DELETE /v1/documents/{doc_id} Write key · cannot be undone

Delete an exact document ID and its canonical text.

Parameter	In	Type	Meaning
`doc_id` *	path	string	A document id.
`dry_run`	query	boolean	`true` reads a complete bounded deletion or merge preview without applying. Write permissions are still required. An incomplete or inaccessible preview refuses; use preview_digest to bind the later apply to what you reviewed.
`preview_digest`	query	string	Digest from a complete dry_run in the same space. A changed affected state refuses apply before mutation.
`operation_id`	query	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Writing nodes and links

Write graph fragments

POST /v1/fragments Write key

Merge authored nodes and edges by exact ID. Supplied props replace the entire object: read, merge and resend to preserve existing fields. Optional claim review returns suggestions separately from partial-write warnings; it does not retire another claim.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`nodes` *	body	array	Nodes matched by id. Optional expected_rev checks the revision from an exact read for the entire fragment before writing. props_patch requires expected_rev and excludes props: nested objects merge, null removes keys, arrays replace. Omitted props preserves it; props replaces the stored value.
`edges`	body	array	Links to add, with `from`, `to` and `type`.
`review_claims`	body	boolean	Optional boolean, `false` by default. Set `true` to compare explicitly keyed Record/Decision claims with this owner's stored claims. Ordinary writes check claim dates without a candidate query. Comparison performs additional candidate queries. Check `advisory_review.state`: `not_requested`, `complete`, `limited` or `unavailable`. Suggestions do not retire claims, and a complete review does not prove a claim true.
`create_only`	body	boolean	Refuse an existing identity before any write. Omit to keep the existing add-or-update behavior.
`operation_id`	body	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.

Success: 200

Preview or delete a node

DELETE /v1/nodes/{id} Write key · cannot be undone

Preview all attached edges with dry_run=true, then delete the exact node ID. Both calls require a write key.

Parameter	In	Type	Meaning
`id` *	path	string	A node id, such as `concept:design-token`.
`dry_run`	query	boolean	`true` reads a complete bounded deletion or merge preview without applying. Write permissions are still required. An incomplete or inaccessible preview refuses; use preview_digest to bind the later apply to what you reviewed.
`stray_type`	query	string	Delete only the copy of this id that was stored under another type (`concept`, `episode`, `record`, `decision`, `bridge` or `entity`). The node the id prefix names stays, and no tombstone is written.
`preview_digest`	query	string	Digest from a complete dry_run in the same space. A changed affected state refuses apply before mutation.
`operation_id`	query	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Delete an edge

DELETE /v1/edges Write key · cannot be undone

Delete one specified relation, including an authored Record edge, while keeping both nodes.

Parameter	In	Type	Meaning
`from_id` *	query	string	Where the link starts.
`to_id` *	query	string	Where the link ends.
`type` *	query	string	`relates_to`, `prerequisite_of`, `derives_from`, `inherits_from`, `returns_to`, `about` or `ATTACHES_TO`. Record edges accept their authored type or `ATTACHES_TO`; `returns_to` connects roles only.
`dry_run`	query	boolean	`true` reads a complete bounded deletion or merge preview without applying. Write permissions are still required. An incomplete or inaccessible preview refuses; use preview_digest to bind the later apply to what you reviewed.
`preview_digest`	query	string	Digest from a complete dry_run in the same space. A changed affected state refuses apply before mutation.
`operation_id`	query	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Public communities

Contribute to a public community

POST /v1/community Write key

Use a full member key on the remote hub to edit wiki pages, discuss, react, report or perform permitted operator actions. The account applies the website permissions and records MCP revisions. Content and creation need a public handle; joining and leaving need sign-in only. Joining grants no extra permission. Read Rules with vinc_conventions first. If a reply is lost, read back before retrying; a failed response may follow a committed write. Share actions publish immutable public snapshots. Agent Take requires a pinned shareId/version/hash, explicit personal or editor-team destination, mutationId and mode=separate or replace. Take needs a full key but no handle or community membership. Replacement requires the exact target id/hash/rev from preview. Added roles remain proposed and absent from host prompts until explicit activation. Read a pending or unknown receipt before retrying.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`action` *	body	string	Choose the operation from this route's enum. Community reads use `agent_detail`, `agent_export`, `agent_take_preview` or `agent_take_result`. Writes include page/social actions, `share_create`, `share_version`, `share_withdraw`, `share_moderate`, `pack_share` and `agent_take`. Preview is read-only; Take requires a full key.
`payload` *	body	object	Fields for the selected operation. Agent reads use shareId and selected version; exports add format. Take preview/result use the selected hash, destination, optional target or mutationId. Take writes add mode=separate\|replace and a stable mutationId; replacement requires exact expectedTarget {id,hash,rev}. Snapshot publication carries role, prompt, tools, public references and license; versions require baseVersion/baseHash. Page saves use slug,title,body,summary,baseRevision; joining/leaving use {}; creation uses slug,name,topic.
`client_name` *	body	string	The calling host's label, 1 to 120 printable characters, recorded in MCP revision history. A label does not grant permission or prove human approval.

Success: 200

Read a shared Agent version

POST /v1/community/read Read key

Use a read-only or full member key on the remote hub with explicit community:<UUID>. Read a selected immutable version, obtain a complete Claude/GPT/SKILL.md/.vincpack export, or inspect a destination target and Take receipt. Pin version and hash; latest is discovery only. Withdrawn bytes require author/operator access or a completed Take for that exact version. Pending or unknown receipts grant no retained access. Preview does not import, activate, execute or grant tools. Agent .vincpack uses pack v2 and requires safe Agent import support; desktop 0.9.7 cannot read it. Oversized MCP artifacts are refused without truncation; use canonical web or REST export for the complete file.

Parameter	In	Type	Meaning
`space` *	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`action` *	body	string	Choose the operation from this route's enum. Community reads use `agent_detail`, `agent_export`, `agent_take_preview` or `agent_take_result`. Writes include page/social actions, `share_create`, `share_version`, `share_withdraw`, `share_moderate`, `pack_share` and `agent_take`. Preview is read-only; Take requires a full key.
`payload` *	body	object	Fields for the selected operation. Agent reads use shareId and selected version; exports add format. Take preview/result use the selected hash, destination, optional target or mutationId. Take writes add mode=separate\|replace and a stable mutationId; replacement requires exact expectedTarget {id,hash,rev}. Snapshot publication carries role, prompt, tools, public references and license; versions require baseVersion/baseHash. Page saves use slug,title,body,summary,baseRevision; joining/leaving use {}; creation uses slug,name,topic.

Success: 200

Duplicates

Merge candidates

GET /v1/merge-candidates Read key

List possible duplicate concepts for review.

Parameter	In	Type	Meaning
`limit`	query	integer	How many results.
`include_structural`	query	boolean	Also include pairs that touch a document's own concept.
`min_score`	query	number	Similarity threshold from 0 to 1.
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Rejected merges

GET /v1/merge-rejections Read key

Read pairs previously ruled distinct.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.

Success: 200

Reject a merge

POST /v1/merge-rejections Write key

Record that two candidates should stay separate.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`a` *	body	string	The first concept id.
`b` *	body	string	The second concept id.
`note`	body	string	Why the two are different, for the next reviewer.
`undo`	body	boolean	Forget an earlier rejection instead.
`operation_id`	body	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.

Success: 200

Merge concepts

POST /v1/nodes/merge Write key · cannot be undone

Merge two reviewed concepts, keeping one identity.

Parameter	In	Type	Meaning
`space`	query	string	`personal`, a team id or `community:<public UUID>`. Defaults to `personal` only when this route allows omission. Community reads and writes require an explicit community space, except creation.
`keep_id` *	body	string	The concept that stays.
`drop_id` *	body	string	The concept merged in and removed.
`dry_run`	body	boolean	`true` reads a complete bounded deletion or merge preview without applying. Write permissions are still required. An incomplete or inaccessible preview refuses; use preview_digest to bind the later apply to what you reviewed.
`preview_digest`	body	string	Digest from a complete dry_run in the same space. A changed affected state refuses apply before mutation.
`operation_id`	body	string	A fresh lowercase UUID for one logical write. Reuse it only with identical arguments. Check this space's receipt after a lost response; unknown is not proof that nothing was applied. Results are historical summaries, and receipts are retained until owner purge with a limit of 5000 per owner.

Success: 200

* marks a required parameter.