API Reference

Graven exposes two public surfaces: a REST Integration API for backend services and a separate MCP endpoint for IDE agents. Use REST when a service must write or query project memory directly. Use MCP when a human or agent is driving the workflow from an IDE.

REST Integration API

Best for service-to-service ingestion, search, CI, workers, and external product integrations.

Base URL:https://api.graven.ai/v1

MCP Agent API

Best for Cursor, Claude Code, and other agents that speak MCP and use OAuth in the browser.

MCP URL:https://api.graven.ai/mcp

REST Integration API

Recommended contract for external services. Integration credentials are tenant-scoped service principals, whileX-Graven-Project-Idselects the exact Graven project for each runtime request.

Integration credential

Recommended for external services and multi-project integrations. Send it asAuthorization: Bearer ....

Project API key

Project-scoped fallback for scripts, CI, or one-off automation. Send it asx-api-key.

MCP OAuth

Use OAuth only for the MCP agent surface. IDE users connect in the browser and choose a project interactively.

Required headers and rules

Header	Meaning
Authorization: Bearer <integration credential>	Recommended for service-to-service integrations. Tenant-scoped credential.
X-Graven-Project-Id: <uuid>	Required on data-plane requests when using an integration credential.
x-request-id: <uuid>	Required on mutation endpoints under /v1/tools/*. Not required for reads or integration control-plane calls.
idempotency-key: <string>	Optional for mutation retries and duplicate protection.
x-api-key: <project api key>	Project-scoped fallback for CI, scripts, or single-project automation.

Integration control-plane endpoints under/v1/integrations/projectsdo not requireX-Graven-Project-Idbecause they create or revoke the binding itself.

External service flow

1. Issue credential

Create an integration credential in the dashboard and hand the raw secret to the partner service once.

2. Bind projects

Map each external project id to a Graven project through the control plane.

3. Call data plane

Send the bearer credential plus the boundX-Graven-Project-Idon runtime reads and writes.

Control plane endpoints

Used by external services to provision, inspect, and revoke project bindings.

GET/v1/integrations/projectsList active and revoked bindings for the authenticated integration credential.

POST/v1/integrations/projectsProvision a Graven project and bind it to an external project id.

POST/v1/integrations/projects/:projectId/revokeRevoke an existing project binding for the authenticated integration credential.

Data plane write endpoints

Mutation endpoints that create or change knowledge. These requirex-request-id.

POST/v1/tools/record_decision202Record a decision

POST/v1/tools/record_assumption202Record an assumption

POST/v1/tools/record_constraint202Record a constraint

POST/v1/tools/record_open_question202Record an open question

POST/v1/tools/record_lesson_learned202Record a lesson learned

POST/v1/tools/capture_knowledge202Raw knowledge capture with candidate type

POST/v1/tools/confirm_entity200Confirm a proposed entity

POST/v1/tools/reject_entity200Reject a proposed entity

POST/v1/tools/confirm_relationship200Confirm a proposed relationship

POST/v1/tools/reject_relationship200Reject a proposed relationship

POST/v1/tools/invalidate_entity200Mark an entity as no longer valid

POST/v1/tools/supersede_entity202Replace an entity with a new version

POST/v1/tools/mark_revalidation200Flag an entity for revalidation

POST/v1/tools/promote_to_org200Promote project-scoped knowledge to org scope

POST/v1/tools/merge_duplicates200Merge duplicate entities

POST/v1/tools/retry_enrichment202Re-run AI enrichment

Data plane read endpoints

Reads, search, context projection, and async operation polling.

GET/v1/entitiesList entities with filters and cursor pagination

GET/v1/entities/:entityIdGet one entity with payload and relationships

GET/v1/entities/:entityId/impactAnalyze downstream impact

GET/v1/entities/:entityId/conflictsCheck conflicting relationships

GET/v1/searchHybrid semantic plus keyword search

GET/v1/contextResume, review, or onboard context view

GET/v1/operations/:operationIdPoll async mutation status

Example: provision or bind a project

curl -X POST https://api.graven.ai/v1/integrations/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_INTEGRATION_CREDENTIAL" \
  -d '{
    "externalProjectId": "buildquest-prod",
    "name": "BuildQuest Production",
    "slug": "buildquest-prod",
    "metadata": {
      "source": "buildquest",
      "accountId": "acct_123"
    }
  }'

Response (201 Created)

{
  "gravenProjectId": "33333333-3333-4333-8333-333333333333",
  "status": "active",
  "created": true,
  "binding": {
    "id": "44444444-4444-4444-8444-444444444444",
    "integrationCredentialId": "55555555-5555-4555-8555-555555555555",
    "integrationName": "BuildQuest runtime",
    "projectId": "33333333-3333-4333-8333-333333333333",
    "projectName": "BuildQuest Production",
    "projectSlug": "buildquest-prod",
    "externalProjectId": "buildquest-prod",
    "metadata": {
      "source": "buildquest",
      "accountId": "acct_123"
    },
    "status": "active",
    "createdAt": "2026-04-10T12:00:00.000Z",
    "revokedAt": null
  }
}

Example: record a decision

curl -X POST https://api.graven.ai/v1/tools/record_decision \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_INTEGRATION_CREDENTIAL" \
  -H "X-Graven-Project-Id: YOUR_GRAVEN_PROJECT_ID" \
  -H "x-request-id: $(uuidgen)" \
  -H "idempotency-key: decision-db-choice-v1" \
  -d '{
    "title": "Use PostgreSQL for primary data store",
    "decision": "PostgreSQL as the primary relational database.",
    "rationale": "Mature, team experience, pgvector support.",
    "alternativesConsidered": "MongoDB, DynamoDB",
    "confidence": "high",
    "decidedIn": "Architecture review",
    "attributedTo": "Jane Smith, CTO",
    "context": "Affects all data access patterns.",
    "tags": ["architecture", "database"]
  }'

Response (202 Accepted)

{
  "requestId": "11111111-1111-4111-8111-111111111111",
  "operationId": "22222222-2222-4222-8222-222222222222",
  "mutationType": "record_decision",
  "status": "accepted",
  "occurredAt": "2026-04-10T12:00:00.000Z",
  "affectedEntities": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "entityType": "decision",
      "status": "pending_enrichment",
      "scopeLevel": "project",
      "enrichmentStatus": "queued"
    }
  ],
  "affectedRelationships": [],
  "quickProposals": [
    {
      "type": "relationship",
      "description": "Potential depends_on relationship with existing caching strategy decisions."
    }
  ]
}

Example: search

curl "https://api.graven.ai/v1/search?query=caching%20strategy&limit=5" \
  -H "Authorization: Bearer YOUR_INTEGRATION_CREDENTIAL" \
  -H "X-Graven-Project-Id: YOUR_GRAVEN_PROJECT_ID"

Response (200 OK)

{
  "query": "caching strategy",
  "totalResults": 2,
  "hasMore": false,
  "items": [
    {
      "entity": {
        "id": "33333333-3333-4333-8333-333333333333",
        "entityType": "decision",
        "status": "confirmed",
        "title": "Use LRU cache in API tier",
        "tags": ["cache", "infra"],
        "enrichmentStatus": "enriched",
        "createdAt": "2026-04-10T12:00:00.000Z",
        "updatedAt": "2026-04-10T12:05:00.000Z"
      },
      "relevanceScore": 0.91,
      "matchHighlight": "Decision mentions caching strategy and eviction policy."
    }
  ],
  "scoringVersion": "hybrid_v1"
}

Entity types

decision

A choice between alternatives

assumption

Something believed but not yet verified

constraint

An external limitation or boundary

open_question

An unresolved question

lesson_learned

Knowledge captured from experience

Relationship types

Type	Meaning	Properties
depends_on	Hard or soft dependency	strength, confidence
derived_from	Source relationship	confidence
supersedes	Replaces a previous entity	-
contradicts	Potential tension, not necessarily a terminal conflict	confidence

MCP Agent API

Use MCP when the user is inside an IDE and the agent should connect through OAuth. The MCP surface uses the same knowledge graph but is optimized for agent workflows rather than raw HTTP clients.

Connection

// .mcp.json
{
  "mcpServers": {
    "graven": {
      "type": "http",
      "url": "https://api.graven.ai/mcp"
    }
  }
}

On first connection the IDE opens a browser for OAuth authentication. The user signs in and chooses a project.

Authentication

OAuth 2.0

Recommended for MCP. The IDE handles the browser login flow and token refresh automatically.

Setup kit

Dashboard setup guides install the MCP config plus Graven guardrails, hooks, and verification steps for supported IDEs.

MCP tools

Available to the agent after connection.

recordRecord a new knowledge entity: decision, assumption, constraint, open question, or lesson learned.

Parameters

entityTypetitlecontextattributedTo...type-specific fields

Returns

Entity id plus enrichment receipt

searchHybrid search across entities using semantic similarity, keyword matching, recency, and graph signals.

Parameters

query?entityType?status?tags?limit?cursor?

Returns

Ranked entity list with relevance scores

get_entityRetrieve a single entity with full payload, relationships, and optional impact or conflict analysis.

Parameters

entityIdinclude?visibility?

Returns

Full entity view with relationships

get_contextProject context for resume, review, and onboarding flows.

Parameters

intent: "resume" | "review" | "onboard"

Returns

Context-specific entity set

reviewConfirm or reject proposed entities and relationships. Batch operations supported.

Parameters

action: "confirm" | "reject"entityIds?relationshipIds?

Returns

Updated status counts

supersedeReplace a confirmed entity with a new version while preserving history.

Parameters

originalEntityIdentityTypetitle...updated fields

Returns

New entity id plus supersedes relationship

manageLifecycle operations such as revalidation, enrichment retry, invalidation, and tag updates.

Parameters

actionentityId...action-specific params

Returns

Operation receipt

feedbackSubmit feedback on enrichment quality to improve future relationship extraction.

Parameters

entityIdratingcomment?

Returns

Feedback id

setupInstall or verify the IDE guardrail kit and fetch setup guides.

Parameters

action: "install" | "verify" | "schema" | "guide"ide?os?

Returns

Action-specific response