SynapSynapDocs
Hub REST API

Knowledge

The Knowledge operations of the Hub REST API (10 operations).

For BuildersOpen-source podSynap CloudGenerated from Synap-core/backend@c31e261ab (main)

List knowledge entries

GET
/knowledge

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

namespace?string
status?string
workspaceId?string
limit?string
offset?string

Response Body

Entries

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://pod.example.com/api/hub/knowledge'
Example Response
[  {    "id": "string",    "key": "string",    "value": null,    "namespace": "string",    "slug": "string",    "status": "string",    "workspaceId": "string",    "author": "string",    "createdAt": "string",    "updatedAt": "string"  }]

Create a knowledge entry

POST
/knowledge

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
key*string
Length1 <= length
value?unknown
namespace?string
slug?string
status?string
workspaceId?|
Formatuuid
author?string

Response Body

Created

application/json
  1. response
id*string
key*string
value?unknown

Arbitrary JSON payload.

namespace?string|null
slug?string|null
status?string
workspaceId?string|null
author?string|null
createdAt?string|
updatedAt?string|
Example Request
curl -X POST 'https://pod.example.com/api/hub/knowledge' \  -H 'Content-Type: application/json' \  -d '{  "key": "string"}'
Example Response
{  "id": "string",  "key": "string",  "value": null,  "namespace": "string",  "slug": "string",  "status": "string",  "workspaceId": "string",  "author": "string",  "createdAt": "string",  "updatedAt": "string"}

Full-text search knowledge entries

Deprecated
GET
/knowledge/search

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

q?string
query?string
workspaceId?string
limit?string

Response Body

Matches

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://pod.example.com/api/hub/knowledge/search'
Example Response
[  {    "id": "string",    "key": "string",    "value": null,    "namespace": "string",    "slug": "string",    "status": "string",    "workspaceId": "string",    "author": "string",    "createdAt": "string",    "updatedAt": "string"  }]

Retrieval — route a query across knowledge substrates

POST
/knowledge/search

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
query*string
Length1 <= length
workspaceId?string
projectId?string
limit?integer
Range1 <= value <= 100
compare?boolean
parseOnly?boolean

Response Body

Routed retrieval result

application/json
  1. response
query*string
routedTo*array<string>
intent*string
primary*string
answers*array<>
degraded*array<string>
understanding*
verdict*string
Value in"confident""ambiguous""empty"
pending?
spaces?|
comparison?
Example Request
curl -X POST 'https://pod.example.com/api/hub/knowledge/search' \  -H 'Content-Type: application/json' \  -d '{  "query": "string"}'
Example Response
{  "query": "string",  "routedTo": [    "string"  ],  "intent": "string",  "primary": "string",  "answers": [    {      "substrate": "string",      "items": [        {          "property1": null,          "property2": null        }      ],      "status": "ok"    }  ],  "degraded": [    "string"  ],  "understanding": {    "property1": null,    "property2": null  },  "verdict": "confident",  "pending": {    "notice": "string",    "matches": [      {        "proposalId": "string",        "proposalType": "string",        "summary": "string",        "entityTitle": "string",        "profileSlug": "string",        "reviewUrl": "string",        "score": 0      }    ]  },  "spaces": {    "matches": [      {        "workspaceId": "string",        "name": "string",        "purpose": "string",        "kinds": [          {            "slug": "string",            "count": 0          }        ]      }    ]  },  "comparison": {    "baseline": [      {        "id": "string",        "title": "string",        "score": 0,        "rank": 0      }    ],    "horizon": [      {        "id": "string",        "title": "string",        "score": 0,        "rank": 0      }    ],    "diff": {      "overlapAtN": 0,      "moved": [        {          "id": "string",          "title": "string",          "baselineRank": 0,          "horizonRank": 0        }      ]    }  }}

Get a knowledge entry by key

GET
/knowledge/{key}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

key*string

Query Parameters

workspaceId?string

Response Body

Entry

application/json
  1. response
id*string
key*string
value?unknown

Arbitrary JSON payload.

namespace?string|null
slug?string|null
status?string
workspaceId?string|null
author?string|null
createdAt?string|
updatedAt?string|
Example Request
curl -X GET 'https://pod.example.com/api/hub/knowledge/string'
Example Response
{  "id": "string",  "key": "string",  "value": null,  "namespace": "string",  "slug": "string",  "status": "string",  "workspaceId": "string",  "author": "string",  "createdAt": "string",  "updatedAt": "string"}

Archive (soft-delete) a knowledge entry

DELETE
/knowledge/{key}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

key*string

Response Body

Archived

application/json
  1. response
success*boolean
Example Request
curl -X DELETE 'https://pod.example.com/api/hub/knowledge/string'
Example Response
{  "success": true}

Upsert a knowledge entry

PUT
/knowledge/{key}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

key*string

Request Body

application/json
  1. body
value?unknown
status?string
author?string

Response Body

Upserted

application/json
  1. response
id*string
key*string
value?unknown

Arbitrary JSON payload.

namespace?string|null
slug?string|null
status?string
workspaceId?string|null
author?string|null
createdAt?string|
updatedAt?string|
Example Request
curl -X PUT 'https://pod.example.com/api/hub/knowledge/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "key": "string",  "value": null,  "namespace": "string",  "slug": "string",  "status": "string",  "workspaceId": "string",  "author": "string",  "createdAt": "string",  "updatedAt": "string"}

BFS traversal of the entity graph

GET
/graph/traverse

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

userId?string
startEntityId*string
maxDepth?string
relationshipTypes?string

Response Body

Traversal results

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://pod.example.com/api/hub/graph/traverse?startEntityId=string'
Example Response
[  {    "property1": null,    "property2": null  }]

DEPRECATED alias of /knowledge/search — raw retrieval door

Deprecated
POST
/knowledge/ask

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
query*string
Length1 <= length
workspaceId?string
projectId?string
limit?integer
Range1 <= value <= 100
compare?boolean
parseOnly?boolean

Response Body

Routed retrieval result (identical to /knowledge/search)

application/json
  1. response
query*string
routedTo*array<string>
intent*string
primary*string
answers*array<>
degraded*array<string>
understanding*
verdict*string
Value in"confident""ambiguous""empty"
pending?
spaces?|
comparison?
Example Request
curl -X POST 'https://pod.example.com/api/hub/knowledge/ask' \  -H 'Content-Type: application/json' \  -d '{  "query": "string"}'
Example Response
{  "query": "string",  "routedTo": [    "string"  ],  "intent": "string",  "primary": "string",  "answers": [    {      "substrate": "string",      "items": [        {          "property1": null,          "property2": null        }      ],      "status": "ok"    }  ],  "degraded": [    "string"  ],  "understanding": {    "property1": null,    "property2": null  },  "verdict": "confident",  "pending": {    "notice": "string",    "matches": [      {        "proposalId": "string",        "proposalType": "string",        "summary": "string",        "entityTitle": "string",        "profileSlug": "string",        "reviewUrl": "string",        "score": 0      }    ]  },  "spaces": {    "matches": [      {        "workspaceId": "string",        "name": "string",        "purpose": "string",        "kinds": [          {            "slug": "string",            "count": 0          }        ]      }    ]  },  "comparison": {    "baseline": [      {        "id": "string",        "title": "string",        "score": 0,        "rank": 0      }    ],    "horizon": [      {        "id": "string",        "title": "string",        "score": 0,        "rank": 0      }    ],    "diff": {      "overlapAtN": 0,      "moved": [        {          "id": "string",          "title": "string",          "baselineRank": 0,          "horizonRank": 0        }      ]    }  }}

Synthesized knowledge answer — retrieve + synthesize

POST
/knowledge/answer

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
query?string
Length1 <= length
question?string
Length1 <= length
workspaceId?string
projectId?string
limit?integer
Range1 <= value <= 100

Response Body

Synthesized answer with sources

application/json
  1. response
answer*string|null
sources*array<>
routedTo*array<string>
degraded*array<string>
spaces?|
error?string
failure?
Example Request
curl -X POST 'https://pod.example.com/api/hub/knowledge/answer' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "answer": "string",  "sources": [    {      "substrate": "string",      "id": "string",      "title": "string"    }  ],  "routedTo": [    "string"  ],  "degraded": [    "string"  ],  "spaces": {    "matches": [      {        "workspaceId": "string",        "name": "string",        "purpose": "string",        "kinds": [          {            "slug": "string",            "count": 0          }        ]      }    ]  },  "error": "string",  "failure": {    "code": "string",    "message": "string",    "retryable": true  }}

Keys

The Keys operations of the Hub REST API (1 operation).

Lifecycle

The Lifecycle operations of the Hub REST API (4 operations).