Agent API Reference

On this page

The Agent API allows external tools and AI agents to read, search, and write content in a Graphora space. All endpoints are authenticated with API tokens.

Base URL: https://api.graphora.app/agent

Authentication

All requests require a Bearer token in the Authorization header. Tokens are prefixed with gra_.

Authorization: Bearer gra_xxxxxxxxxxxxxxxxxxxxx

Each token is scoped to a single space and linked to exactly one scratchpad document. The scratchpad is a regular page in your space that the agent writes to — think of it as the agent’s notebook. Read endpoints (graph, doc, search) can read any document in the space, while write endpoints (PUT /agent/doc, PATCH /agent/doc/tasks/:uniqueId) always target the token’s scratchpad page.

Endpoints

GET /agent/graph

Returns the full knowledge graph for the space: all documents as nodes and their wiki-link connections as edges.

Response

{
  "nodes": [
    {
      "id": "uuid",
      "label": "Document Title",
      "isFavorite": false,
      "isJournal": false,
      "journalDate": null
    }
  ],
  "edges": [
    {
      "source": "uuid-of-source-doc",
      "target": "uuid-of-target-doc"
    }
  ]
}

Field	Type	Description
`nodes[].id`	`string`	Document UUID
`nodes[].label`	`string`	Display name (or journal date, or `"Untitled"`)
`nodes[].isFavorite`	`boolean`	Whether the document is favorited
`nodes[].isJournal`	`boolean`	Whether this is a journal entry
`nodes[].journalDate`	`string \| null`	`YYYY-MM-DD` if journal, otherwise `null`
`edges[].source`	`string`	Source document UUID
`edges[].target`	`string`	Target document UUID

GET /agent/doc/:docId

Returns a single document with its content represented as an outline tree.

Path Parameters

Parameter	Type	Description
`docId`	`string`	Document UUID

Response

{
  "id": "uuid",
  "displayName": "My Document",
  "isJournal": false,
  "journalDate": null,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-04-01T14:22:00.000Z",
  "content": [
    {
      "text": "A bullet point with a [[Wiki Link]]",
      "children": [
        {
          "text": "A nested child item"
        }
      ]
    },
    {
      "text": "Buy groceries",
      "task": true,
      "checked": false,
      "scheduledFor": "2026-04-05",
      "dueDate": "2026-04-07"
    }
  ]
}

Field	Type	Description
`id`	`string`	Document UUID
`displayName`	`string \| null`	Document title
`isJournal`	`boolean`	Whether this is a journal entry
`journalDate`	`string \| null`	`YYYY-MM-DD` if journal
`createdAt`	`string`	ISO 8601 timestamp
`updatedAt`	`string`	ISO 8601 timestamp
`content`	`OutlineItem[]`	Document content as an outline tree

OutlineItem

Field	Type	Description
`text`	`string`	Plain text content of the item. Wiki links appear as `[[Label]]`
`children`	`OutlineItem[]`	(optional) Nested child items
`task`	`boolean`	(optional) `true` if this is a task item
`checked`	`boolean`	(optional) Whether the task is completed
`scheduledFor`	`string`	(optional) Scheduled date (`YYYY-MM-DD`)
`dueDate`	`string`	(optional) Due date (`YYYY-MM-DD`)

Errors

Status	Description
`404`	Document not found in this space

GET /agent/search

Search documents by title or content.

Query Parameters

Parameter	Type	Default	Description
`q`	`string`	(required)	Search query
`limit`	`number`	`20`	Max results (1–100)

Response

[
  {
    "id": "uuid",
    "displayName": "Matching Document",
    "isJournal": false,
    "journalDate": null,
    "snippet": "First 200 characters of the document content..."
  }
]

Field	Type	Description
`id`	`string`	Document UUID
`displayName`	`string \| null`	Document title
`isJournal`	`boolean`	Whether this is a journal entry
`journalDate`	`string \| null`	`YYYY-MM-DD` if journal
`snippet`	`string`	First 200 characters of plain text content

Returns an empty array if q is missing or empty.

PUT /agent/doc

Append content to the token’s linked scratchpad document. Wiki links in the text ([[Page Name]]) are automatically resolved to existing documents.

Request Body

{
  "content": [
    {
      "text": "A new bullet point"
    },
    {
      "text": "A task with a link to [[My Page]]",
      "task": true,
      "checked": false,
      "dueDate": "2026-04-10"
    },
    {
      "text": "Parent item",
      "children": [
        { "text": "Child item 1" },
        { "text": "Child item 2" }
      ]
    }
  ]
}

Field	Type	Max Length	Description
`content`	`OutlineItem[]`	—	Items to append
`content[].text`	`string`	10,000	Item text. Use `[[Name]]` for wiki links
`content[].children`	`OutlineItem[]`	—	(optional) Nested children
`content[].task`	`boolean`	—	(optional) Mark as task item
`content[].checked`	`boolean`	—	(optional) Task completion state
`content[].scheduledFor`	`string`	—	(optional) `YYYY-MM-DD`
`content[].dueDate`	`string`	—	(optional) `YYYY-MM-DD`

Response

{
  "id": "uuid-of-scratchpad-doc",
  "status": "appended"
}

Errors

Status	Description
`400`	Token has no linked scratchpad document

PATCH /agent/doc/tasks/:uniqueId

Update the checked state of a task item in the scratchpad document.

Path Parameters

Parameter	Type	Description
`uniqueId`	`string`	The task item’s unique ID

Request Body

{
  "checked": true
}

Field	Type	Description
`checked`	`boolean`	New checked state

Response

{
  "id": "uuid-of-scratchpad-doc",
  "updated": true
}

Errors

Status	Description
`400`	Token has no linked scratchpad document

Common Errors

Status	Description
`401`	Missing, invalid, or expired API token

Examples

# Get the knowledge graph
curl -H "Authorization: Bearer gra_your_token_here" \
  https://api.graphora.app/agent/graph

# Read a document
curl -H "Authorization: Bearer gra_your_token_here" \
  https://api.graphora.app/agent/doc/DOCUMENT_UUID

# Search documents
curl -H "Authorization: Bearer gra_your_token_here" \
  "https://api.graphora.app/agent/search?q=meeting+notes&limit=10"

# Append content to scratchpad
curl -X PUT \
  -H "Authorization: Bearer gra_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"text": "New insight from research", "task": true, "checked": false}]}' \
  https://api.graphora.app/agent/doc

# Check off a task
curl -X PATCH \
  -H "Authorization: Bearer gra_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"checked": true}' \
  https://api.graphora.app/agent/doc/tasks/TASK_UNIQUE_ID